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Purpose 


This manual describes the various features of Common Business Oriented Language 
(COBOL) ANSI-74 as implemented on Unisys A Series systems and provides reference 
material about the COBOL language 


Acknowledgment 


Any organization wishing to reproduce this COBOL manual in whole or in part as the 
basis for an instruction manual or for any other purpose is free to do so. However, all 
such organizations are requested to reproduce this section as part of the introduction 
to the manual. Those using a short passage, as in a book, need not quote this entire 
preface. 


COBOL is an industry language and is not the property of any company or group of 
companies or of any organization or group of organizations. 


No warranty, expressed or implied, is made by any contributor or by the COBOL 
Committee as to the accuracy and functioning of the programming system and language. 
Moreover, no responsibility is assumed by any contractor or by the committee in 
connection therewith. 


Procedures have been established for the maintenance of COBOL. Inquiries concerning 
the procedures for proposing changes should be directed to the Executive Committee of 
the Conference on Data Systems Language. 


The authors and copyright holders of the copyrighted material used herein have _ 
specifically authorized the use of this material, in whole or in part, in the COBOL 
specifications. These authors or copyright holders are the following: 


e FLOW-MATIC (Trademark of Sperry Rand Corporation), Programming for the 
Univac RI and II, Data Automation Systems, copyrighted 1958, 1959 by Sperry 
Rand Corporation 


e IBM Commercial Translator, Form No. F28-80 13, copyrighted 1959 by International 
Business Machines Corporation 


e FACT, DSI 27A5260-2760, copyrighted 1960 by Minneapolis—-Honeywell 


Such authorization extends to the reproduction and use of COBOL specifications in 
programming manuals or similar publications. 
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Scope 


This two-volume set provides a complete description of COBOL74 as implemented 
for use on A Series systems. This volume provides the syntax and rules specific to 
COBOL74. Volume 2 contains the syntax for using COBOL74 to write application 
programs that interface with the following products: 

e Advanced Data Dictionary System (ADDS) 

e Data Management System IT (DMSID) 

e Communications Management System (COMS) 

e DMSII Transaction Processing System (TPS) 

e Semantic Information Manager (SIM) 

e Screen Design Facility (SDF) 

e Screen Design Facility Plus (SDF Plus) 


Audience 


The primary audience for this manual includes programmers and system analysts 
who are experienced in developing, maintaining, and reading COBOL programs. The 
secondary audience consists of technical support personnel and information systems 
management. A possible tertiary audience includes programmers who are learning 
COBOL, but the manual is not designed for this audience. 


Prerequisites 


To use this manual, you should be familiar with the general concepts of COBOL 
programming. 


How to Use This Manual 


vi 


Throughout this manual, Volume 2 refers to the A Series COBOL ANSI-74 
Programming Reference Manual, Volume 2: Product Interfaces, unless a different 
manual title is specified. — 


Unisys standard COBOL74 is based on, and is fully compatible with, the American 
National Standard programming language COBOL, X3.23-1974. Throughout this 
manual, extensions to the American National Standard Programming Language COBOL, 
X3.23-1974 are identified as such with the phrase Unisys extension. 


The elements of the language are described in the order in which they are coded in a 
program. The IDENTIFICATION DIVISION is described first; the PROCEDURE 
DIVISION is described last. For a statement or a clause, individual elements are 
described in the order in which they are listed in the format. 
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COBOL modules including the Report Writer, Debugging, Communication, 
Segmentation, and Inter-Program Communication modules are described in separate 
sections. 


The GENERALSUPPORT system library must be installed before you can use the 
features of the COBOL74 compiler described in this manual. 


Organization 


This manual has 17 sections and 4 appendixes. In addition, a glossary, a bibliography, and 
an index appear at the end of the manual. 


Section 1. Program Structure 


This section includes a brief introduction to the COBOL language and to source 
programs. 


Section 2. Language Elements 


This section describes the elemental constructs of COBOL (including words, names, 
literals, and character strings) and the rules governing their association into sentences, 
clauses, and paragraphs. 


Section 3. File and Task Concepts 


This section describes a number of concepts pertaining to files and tasks. These concepts 
include the physical and logical aspects of a file, file organization, file attributes, task 
attributes, and related concepts. 


Section 4. IDENTIFICATION DIVISION 


This section specifies the function, format, and elements of the IDENTIFICATION 
DIVISION of a COBOL source program. 


Section 5. ENVIRONMENT DIVISION 


This section specifies the function, format, and elements of the ENVIRONMENT 
DIVISION of a COBOL source program. 


Section 6. Data Concepts 


This section describes a number of concepts pertaining to records and data. The record 
concept encompasses structure, record level, and data items in the record. The data 
concept includes data type, data alignment, and data referencing. The table concept for 
handling sets of data includes subscripting and indexing. 


Section 7. DATA DIVISION 


This section specifies the function, format, and elements of the DATA DIVISION of a 
CORO source program. 
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Section 8. PROCEDURE DIVISION Concepts 


This section includes a general description of the PROCEDURE DIVISION structure, 
statements and sentences, functions, arithmetic expressions, conditions, and the 
functions of the verbs. 


Section 9. PROCEDURE DIVISION Statements 


This section specifies the function, format, and elements of the PROCEDURE 
DIVISION of a COBOL source program. 


Section 10. Segmentation 


This section describes the standard COBOL segmentation module. This module is used 
to divide a very large program into segments. 


Section 11. Debugging 


This section describes the COBOL debug module. This module is used to monitor data 
item values and program-control status during program execution. A programming 
example is provided at the end of the section. 


Section 12. Report Writer 


This section describes the Report Writer module of COBOL. A programming example is 
provided at the end of the section. — 


Section 13. ANSI Inter-Program Communication (IPC) 
This section describes the COBOL Inter-Program Communication (IPC) module. 


Section 14. COMMUNICATION SECTION 


This section describes the COBOL communications module and COBOL message control 
system (MCS). 


Section 15. Libraries 


This section describes the A Series library feature, which is a separate feature from the 
COBOL library feature and the COBOL IPC module. 


Section 16. Internationalization 


‘This section includes a general introduction to internationalization concepts and a 
summary of CENTRALSUPPORT library procedures. Each library procedure, with its 
parameters and result, is presented in alphabetical order. A list of error messages and 
values ends the section. 
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Section 17. Control of the Compilation Process 


This section describes the input and output files used by the COBOL compiler and the 
compiler control options that direct compiler processing of COBOL source input. 


Appendix A. General Format Notation 
This appendix explains the notation aids for interpreting COBOL syntax. 


Appendix B. Reserved Words and Keywords 
This appendix lists the reserved words in alphabetical order. 


Appendix C. EBCDIC and ASCII Character Sets 
This appendix lists the values for the EBCDIC and ASCII characters sets. 


Appendix D. Examples 
This appendix displays examples that show various constructs. 


Related Product Information 


A Series CANDE Configuration Reference Manual (form 8600 1344) 


This manual describes the commands used to perform CANDE control functions. and 
data communications network control functions. It also describes how to configure 
CANDE to meet the resource requirements of the installation. This manual is written 
for system administrators and operators. 


A Series COBOL ANSI-74 Programming Reference Manual, Volume 2: Product 
Interfaces (form 8600 0130) 


This manual describes the extensions to the standard COBOL ANSI-74 language. 
These extensions are designed to allow application programs to interface with the 
Advanced Data Dictionary System (ADDS), the Communications Management System 
(COMS), the Data Management System IT (DMSII), the DMSII Transaction Processing 
System (TPS), the Screen Design Facility (SDF), the Screen Design Facility Plus (SDF 

' Plus), and Semantic Information Manager (SIM) products. This manual is written for 
programmers who are familiar with COBOL74 programming language concepts and 
terms. . . 


A Series COBOL ANSI-74 Test and Debug System ( TADS) Programming Guide 
(form 1169901) 


This guide documents COBOL74 TADS, an interactive tool for testing and debugging 
COBOL74 programs and libraries. This guide is written for programmers familiar with 
COBOL74 programming language concepts and terms. 
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A Series Distributed Systems Service (DSS) Operations Guide 
(form 8600 0122) 


This guide describes the capabilities and features of DSS Services. It is intended for 
system operators, system administrators, and general computer users. 


A Series Editor Operations Guide (form 8600 0551) 


This guide describes the operation of the Editor, an interactive tool for creating 

and modifying text and program files. This guide is written for experienced and 
inexperienced users who are responsible for creating and maintaining text and program 
files. | 


A Series File Attributes Programming Reference Manual (form 8600 0064). 
Formerly A Series I/O Subsystem Programming Reference Manual 


This manual contains information about each file attribute and each direct I/O buffer 
attribute. The manual is written for programmers and operations personnel who need 
to understand the functionality of a given attribute. The A Series I/O Subsystem 
Programming Guide isacompanion manual. _ 


A Series I/O Subsystem Programming Guide (form 8600 0056). Formerly 
A Series I/O Subsystem Programming Reference Manual 


This guide contains information about how to program for various types of peripheral 
files and how to program for interprocess communication, using port files. This guide is 
written for programmers who need to understand how to describe the characteristics of 
a file in a program. The A Series File Attributes Programming Reference Manual isa 
companion manual. : . | | 


A Series MultiLingual System (MLS) Administration, Operations, and 
Programming Guide (form 8600 0288) 


This guide describes how to use the MLS environment, which encompasses many Unisys 
products. The MLS environment includes a collection of operating system features, 
productivity tools, utilities, and compiler extensions. The guide explains how these 
products are used to create application systems tailored to meet the needs of users in 

a multilingual or multicultural business environment. It explains, for example, the 
procedures for translating system and application output messages, help text, and 

user interface screens from one natural language to one or more other languages; for 
instance, from English to French and Spanish. This guide is written for international 
vendors, branch systems personnel, system managers, programmers, and customers who 
wish to create customized application systems. 


A Series System Commands Operations Reference Manual (form 8600 0395) 


This manual gives a complete description of the system commands used to control 
system resources and work flow. This manual is written for systems operators and 
. administrators. 


A Series System Software Support Reference Manual (form 8600 0478) 


This manual describes a number of facilities used for system monitoring and debugging, 
including BARS, DUMPANALYZER, LOGANALYZER, and LOGGER. It also describes 
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the format of the SUMLOG file. This manual is written for system support personnel 
and operators. 


A Series System Software Utilities Operations Reference Manual 
(form 8600 0460) 


This manual provides information on the system utilities, such as DCSTATUS, 
FILECOPY, and DUMPALL. This manual is written for applications programmers and 
operators. 


A Series Task Attributes Programming Reference Manual (form 8600 0502). 
Formerly the A Series Work Flow Administration and Programming Guide 


This manual describes all the task attributes available on A Series systems. It also gives 
examples of statements for reading and assigning task attributes in various programming 
languages. The A Series Task Management Programming Guide is a companion 
manual. 


A Series Transmission Control Protocol/Internet Protocol (TCP/IP) 
Implementation Guide (form 1221328) 


This guide explains how to install the TCP/IP software in an A Series BNA Version 2 
network. It also describes related features and dependencies, such as Distributed 
Systems Services (DSS) features supported by TCP/IP and the interfaces to the 
Ethernet™ local area network (LAN) and X.25 wide area network (WAN) provided by 
the Unisys CP 2000 communications processor. 


A Series Work Flow Language (WFL) Programming Reference Manual (form 
8600 1047) ’ 


This manual presents the complete syntax and semantics of WFL. WFL is used to 
construct jobs that compile or run programs written in other languages and that perform 
library maintenance such as copying files. This manual is written for individuals who 
have some experience with programming in a block-structured language such as ALGOL 
and who know how to create and edit files using CANDE or the Editor. 


Ethernet is a trademark of Xerox Corporation. 
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section 1- 
Program Structure 


COBOL74 is a programming language based on the English language and, as such is 
composed of paragraphs, sentences, clauses, and words. The language is designed so 
that your source program is self-explanatory to someone who does not understand 
COBOL74. This section describes the following: 


e The components of a source program 


e The rules for entering the components in the source program 


Source Program Components 


A source program is code written in COBOL74 that the compiler accepts as input. When 
you compile the source program, the compiler verifies that your code follows the rules 
presented in this manual and translates the source program into an object program. The 
object program directs the computer to operate on the data. If the compiler indicates 
that your source program needs corrections, you can make the appropriate changes and 
then recompile it. The object program always reflects the source program you create. 


Program Divisions 


A COBOL74 source program is divided into four parts called divisions. The divisions 
must appear in the following order: 


IDENTIFICATION DIVISION 


1. 

2. ENVIRONMENT DIVISION 
3. DATA DIVISION 

4. PROCEDURE DIVISION 


A division header consists of the name of a division, the word DIVISION, anda period. 
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Division Name Purpose of Division 


Table 1-1 describes the purpose of each division. 


- Table 1~1. Purpose of COBOL74 Divisions 


IDENTIFICATION Identifies and provides documentation about the source program. 


ENVIRONMENT Specifies the computer system and associates files with I/O devices. 


DATA Describes the structure of the data, the constants to be used, the 
intermediate storage areas, and any external data. 


PROCEDURE Instructs the computer to perform the steps necessary to solve the 
problem addressed by the source program. This division uses the 
data described in the DATA DIVISION. 


Sections 


The ENVIRONMENT, DATA, and PROCEDURE DIVISIONs can be subdivided into 
sections. A section further identifies the purpose of a division. 


A section begins with a name that identifies the section. COBOL74 specifies the names 
of sections in the ENVIRONMENT and DATA DIVISIONs. You specify names of 
sections in the PROCEDURE DIVISION. 


A section header consists of the name of the section, the word SECTION and a period. 
A section continues with one or more successive paragraphs that follow the period. 

A section ends immediately before the next section, at the end of the division, or at 
the keywords END DECLARATIVES in the DECLARATIVES SECTION of the 
PROCEDURE DIVISION. 
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Table 1-2 describes the sections associated with each division. 


Division Name 
IDENTIFICATION 
ENVIRONMENT 


PROCEDURE 


+ Unisys extension 


Paragraphs 


Table 1-2. Purpose of Sections 


Section Name 
None 
CONFIGURATION 
INPUT-OUTPUT 


FILE 
DATA-BASEt 


WORKING-STORAGE 
LOCAL-STORAGET: 


LINKAGE 


COMMUNICATION 


REPORT 


User defined 


Purpose of Section 

Not applicable 

Specifies computer equipment 
Associates files with specific devices 


Describes the record structure of files 


‘Describes one or more data-bases that can © 


be used by the COBOL program 


Describes intermediate data items 


Describes data to be either passed or 
received as parameters to an external 
procedure 


Describes data items to be referenced by the | 
calling program and the called program 


Describes the data items in the source 
program that serve as the interface between 
the data communications interface (DC!) 
library and the program 


Describes the contents and format of 
generated reports for the Report Writer 


Groups paragraphs into sections that you 
define 


In the IDENTIFICATION and ENVIRONMENT DIVISIONS, a paragraph begins with a 
header that identifies the paragraph. A paragraph header consists of a reserved word 
followed by a period. The paragraph continues with one or more successive clauses or 
entries. 


In the PROCEDURE DIVISION, a paragraph begins with a user-defined word called a 
paragraph-name. It is followed by a period and optionally one or more entries. 


A paragraph ends immediately before the next paragraph header or section name, at the 


end of the division, or at the keywords END DECLARATIVES in the DECLARATIVES 
SECTION of the PROCEDURE DIVISION. 
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Example 


Example 1-1 shows examples of paragraphs in the IDEN TIFICATION ; 
ENVIRONMENT, and PROCEDURE DIVISIONSs. 


@1@00@ IDENTIFICATION DIVISION. 

919959*The PROGRAM-ID paragraph header is a reserved word. 
919198 PROGRAM-ID. GUEST-CREDIT-AUTHORIZATION. 

198008 ENVIRONMENT DIVISION. 

198858 CONFIGURATION SECTION. 

189158*The SOURCE-COMPUTER paragraph header is a reserved word. 
188288 SOURCE-COMPUTER. MICROA. 

190258 INPUT-OUTPUT SECTION. 

190398*The FILE-CONTROL paragraph header is a reserved word. 
19835@ FILE-CONTROL. 


200802 PROCEDURE DIVISION. 
200858* You define paragraph-names in the PROCEDURE DIVISION. 


- 208190 MAIN-PARAGRAPH. 


° 
e 


Example 1-1. Coding Paragraphs 


Sentences 


A sentence consists of one or more statements. You must end a sentence with a period. 
A sentence can be one of the following three types: 


e Acompiler-directing sentence that directs the compiler to take a specific action 
during the compilation process. 


e Aconditional sentence that tests a truth value and specifies an action depending on 
the result of the test. 


e An imperative sentence that specifies an unconditional action to be taken. 
Example 


The following is an example of a conditional sentence: 


IF BALANCE LESS THAN ZERO 
PERFORM PROCESS-DEBIT 
ELSE | 
NEXT SENTENCE. 


See Also 


For more information about types of sentences, refer to Section 8, “PROCEDURE 
DIVISION Concepts.” 
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Statements 
A statement is a syntactically valid combination of words and symbols beginning with 
a COBOL74 verb. A statement ends whenever the compiler detects a new verb or a 
period. 

Clauses, Phrases, and Options 
A clause is a set of consecutive COBOL74 words that represents a valid portion of a 
statement or entry. A phrase is a set of consecutive COBOL74 words that represents a 


valid portion of a statement, entry, or clause. In this manual, optional phrase and clauses 
are often referred to as options. 


Words 


A word is a string of characters that form a valid COBOL74 word for creating valid 
phrases, clauses, statement, sentences, paragraphs, sections, and divisions. 


See Also 


For a complete description of the rules for forming words, refer to Section 2, “Language 
Elements.” 


Line Layout 


The compiler expects the components of your source program to appear in specific areas 
along a line of code. Each line has 80 positions, which are grouped into five areas that 
make up the line format (also called the reference format), as shown in Figure 1-1. 


COLUMN 
1-6 8-11 12 - 72 73 - 88 


Figure 1-1. Line Format 


LY 


8600 0296-000 1-5 


Program Structure 


Table 1-8 shows the columns associated with each area, the name of the area, and the 
program components that can begin in that area. 


- Table 1-3. Placement of Source Program Component within Areas 


Columns Acceptable Entries 


Sequence area Sequence number 


Indicator area | Asterisk (*), slash (/), D, hyphen (—), or 
dollar sign ($) 


Area A 
: Division header 


Section header 

Paragraph header 

File description (FD) entry 

Sort merge description (SD) entry 
Level numbers 

DECLARATIVES keyword 

END DECLARATIVES keyword 


Area B 
Sentences 


e Level numbers other than 01 or 77 


Identification area Comment entries 


See Also 
For information about using the FREE compiler option to remove the margin restrictions 
required by COBOL74, refer to “FREE” in Section 17, “Control of the Compilation 
Process.” : 

Columns 1—6: Sequence Area 
The sequence area contains a 6-digit sequence number that is incremented with each 


successive line. These numbers are generated automatically when you use CANDE or 
the Editor. 
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Column 7: Indicator Area 


The indicator area contains one of the following five characters. Each character indicates 
the specified special purpose for the line. 


An asterisk (*) indicates the line is a comment line. 


A slash (/) indicates the line is a comment line and causes the printer to eject a page 
and print the comment at the top of the source listing. 


The letter D indicates the line is a debugging line. 
A hyphen (—) indicates the line is a continuation line. 
A dollar sign ($) indicates the line is a compiler control record. 


See Also 


For more information about these types of lines, refer to “Special Purpose Lines” later in 
this section. 


Columns 8-11: Area A 


Division, section, and paragraph headers, level indicators, the level numbers 01 and 
77 , and the keywords for declaratives must begin in area A. You can begin your entry 
anywhere within area A. It is acceptable for your entry to extend into area B. 


The rules for forming division and section headers are as follows: 


Enter the division or section name in area A. 

Follow the name by at least one space. 

Enter DIVISION or SECTION, whichever is appropriate. 
End the entry with a period. 


The rules for forming paragraph headers are as follows: 


Enter the name of the paragraph. » 


Follow the name with a period. | 


The rules for forming the indicators of a file description (FD) or sort-merge description 
(SD) entry or a level-number 01 or 77 entry are as follows: . 


Enter FD, SD, 01, or 77, whichever is appropriate. 


Follow the entry with the appropriate associated name and descriptive information. 
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The rules for forming declarative keywords are as follows: 


e Enter DECLARATIVES. ona line by itself at the beginning of the DECLARATIVES 
SECTION of the PROCEDURE division. 


e Enter END DECLARATIVES. ona line by itself at the end of the DECLARATIVES 
SECTION. 


Example 


_ Example 1-2 shows coding of area A entries. 


098108 IDENTIFICATION DIVISION. 
@@620B ENVIRONMENT DIVISION. 
908388 CONFIGURATION SECTION. 
92B496 SOURCE-COMPUTER. MICROA. 
9G058G INPUT-OUTPUT SECTION. 
O@8680 FILE-CONTROL. 


981988 DATA DIVISION. 
601108 FILE SECTION. 
981206 FD GUEST-FILE 


881408 @1 NAME-RECORD. 


@918GB WORKING-STORAGE SECTION. 
001988 77 EOF-FLAG. 


993988 PROCEDURE DIVISION. 
003198 DECLARATIVES. 


e 


093308 END DECLARATIVES. 
623408 MAIN SECTION. 


e 
. 


Example 1-2. Coding Area A Entries 


See Also 


e For information about level numbers, refer to Section 7, “DATA DIVISION.” 


e For information about declaratives, refer to Section 8, “PROCEDURE DIVISION 
Concepts.” 
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Columns 12-72: Area B 


The bulk of your code, including sentences, statements, clauses, and many level-number 
entries, begin in area B. Your entry can begin anywhere within area B. 


In the DATA DIVISION, all level numbers other than 01 and 77 can begin anywhere in 
area A or B. 


The first sentence or entry in a paragraph begins either on the same line as the 
paragraph name or in area B of the next nonblank line that is not a comment line. 
Additional sentences begin after the previous sentence in area B of the same line or in 
area B of the next nonblank line that is not a comment line. 


For readability, Unisys recommends that you begin all level numbers other than 01 or 

77 in area B and that you indent each successively higher level number two to four 
positions. In addition, Unisys suggests that you define level numbers with an increment 
value greater than one so that it is possible to insert new levels between two levels, if the 
need arises. ; 


Example 


Example 1-3 shows the use of indentation to make your coding more readable. 
Subordinate entries are indented four spaces. For sa a MONTH, DAY, and YEAR 
are all elements of DATER. 


G18090* Indentation improves the readability of your program. 
G10850* 

918196 91 INPUT-RECORD. 

188352 83 DATER 

192489 @5 MONTH PIC 99. 


188458 @5 DAY PIC 99, 
189598 ‘@5 YEAR PIC 99. 
198559 83 FILLER PIC X(33). 


190602 66 IN-DATE RENAMES MONTH THRU YEAR. 
Example 1-3. Coding Area B Entries for Readability 


Columns 73-80: Identification Area 


This area is an optional area. You can use it for documentation purposes. 
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_ Special-Purpose Lines 


Special purpose lines are lines that have a special character in the indicator area 
(column 7) or are blank. These include comment lines, continuation lines, debugging 
lines, compiler control options, and blank lines. 


Comment Lines 


A comment line is any line with either an asterisk (*) or a slash (/) in the indicator area 
(column 7) of the line. A comment line can appear anywhere in a source program and 
can use any combination of characters from the character set of the computer, not just 
the characters in the COBOL74 character set. You can use successive comment lines. 


If you use the slash character to indicate a comment, the printer ejects a page before 
printing the comment on the output listing of the compiler. 


Example 


Example 1-4 shows the use of comment lines. 


100188 IDENTIFICATION DIVISION. 

186288* The purpose of this program is to ... 

198380* Notice that comments can use lowercase letters. 
196498 PROGRAM-ID. GUEST-CREDIT-AUTHORIZATION. 

190500/ This comment is printed at the top of a new page. 
19269@ ENVIRONMENT DIVISION. 


Example 1-4. Coding Comment Lines 


Continuation Lines 


A continuation line is a line that is continued from a previous line. You indicate a 
continuation line with a hyphen (-) in the indicator area (column 7). The hyphen means 
that the first nonblank character in area B (columns 12-72) of the continuation line 
follows the last nonblank character of the preceding line, with no spaces. inserted. Area 
A (columns 8-11) of a continuation line must be blank. If no hyphen is present in the 
indicator area of a line, the compiler assumes that the last character in the preceding line 
is followed by a space. You can use successive continuation lines. 
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_ The rules for using a continuation line with a nonnumeric literal (which must begin with 
a quotation mark) or an undigit literal (which must begin with a commercial at sign) are 
as follows: 


e Use all 72 positions on the line to be continued. All spaces at the end of the line are 
considered to be part of the literal. 


e Donot close the literal in column 72 with a quotation mark for the nonnumeric 
- literal or a commercial at sign (@) for the undigit literal because doing so will delimit 
the literal and prevent it from being continued. 


_e Enter as the first nonblank character in area B a quotation mark for the nonnumeric 
literal or a commercial at sign for the undigit literal. The literal continues with the — 
character immediately after the quotation mark or a commercial at sign. 


Example 


Example 1-5 shows coding of continuation lines. 


180158*Line 198288 continues the clause begun on the preceding line. 
108198 SELECT GUEST-FILE ASSIGN TO DISK OR 
190286- GANIZATION IS SEQUENTIAL. 


198798* Line 109920 continues a nonnumeric literal. 


198888 77 HEADER-LINE PIC X(6@) VALUE IS " JANUARY FEBRUARY 
128989-~ "MARCH APRIL = MAY JUNE mis 
181988 


1915@8*Line 192888 continues an undigit literal. 

191988 77 HEX-LITERAL PIC X(38) VALUE IS @AAAAAAAAAABBBBBBBBBBCCC 
192088- @CCCCCCE. 

192388 

192598* The first quote continues the nonnumeric literal; the second 
192558* quote ends the literal. 

182686 @1 WARNING MESSAGE PIC X(24) VALUE IS "WRONG ENTRY FOR THIS KEY 
192788- sr 


Example 1-5. Coding Continuation Lines 


Debugging Lines 


A debugging line is any line with a D in the indicator area (column 7) of the line. A 
debugging line with spaces in columns 8 through 72 is considered to be the same as a 
blank line. ‘You can enter a debugging line anywhere after the OBJECT-COMPUTER 
paragraph. . 


The debugging module is activated when you specify the WITH DEBUGGING MODE 
clause in the SOURCE-COMPUTER paragraph. If you do not activate the debugging © 
module, the compiler treats a debugging line like a comment line. Therefore, you should 
make sure that your program is syntactically correct when the debugging lines are 
considered to be comment lines. 
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You can use successive debugging lines and can continue debugging lines; however, each 
continuation line must contain a D in the indicator area, and character strings cannot be 
continued across multiple lines. 


Example 


Example 1-6 shows the use of debugging lines. 


19000 IDENTIFICATION DIVISION. 
19800@ ENVIRONMENT DIVISION. 
198188 SOURCE-COMPUTER. MICROA WITH DEBUGGING MODE 


162628 WORKING STORAGE SECTION. 

196788077 PERFORMANCE-COUNT PIC 9(4). 
19@888D77 BAD-RECORDS PIC 9(4). 

. 188986077 RATIO PIC 9(4).99. 


181@@@ PROCEDURE DIVISION. 

192800 OPEN-IT. 

102186 OPEN INPUT GUEST-FILE. 

1930080 | MOVE ZEROS TO PERFORMANCE-COUNT, BAD-RECORDS, RATIO. 
194808 READ-IT. | 

184188 READ GUEST-FILE AT END GO TO FINISH-IT. 

195@@@D ADD 1 TO PERFORMANCE-COUNT. 

186@@0D | IF IN-KEY NOT NUMERIC ADD 1 TO BAD-RECORDS. 


197068 | GO TO READ-IT. 

198880 FINISH-IT. 

188182 CLOSE GUEST~FILE. 

169820D DIVIDE PERFORMANCE-COUNT BY BAD-RECORDS GIVING RATIO. 


Example 1-6. Coding Debugging Lines 


See Also 


e For information about the WITH DEBUGGING MODE clause, refer to Section 4, 
“IDENTIFICATION DIVISION.” 


e For information about the debug module, refer to Section 11, “Debugging.” 
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Compiler Control Options 


A compiler control option is any line with a dollar sign ($) in the indicator area (column 7) 
of the line. This line specifies compiler control options to use during the compilation 
process. 


See Also 


For a discussion of the available compiler control options and their uses, refer to 
Section 17, “Control of the Compilation Process.” 


Blank Lines 


A blank line is a line that has no entries in the indicator area, area A, or area B. You 
can use a blank line anywhere in the source program except immediately preceding a 
continuation line. 
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Language Elements 


This section describes the following elements used to form the components of a source 
program: 

e Character set 

e Separators 


e Character strings 


Character Set 


The most basic and indivisible unit of the COBOL74 language is the character. The set 
of characters you use to write COBOL74 programs includes the letters of the alphabet, 
digits, and special characters. The character set consists of 52 characters, including the 
51 characters specified in the ANSI-74 standard plus the commercial at sign (@), which 
is a Unisys extension. You link these individual characters together to form character 
strings and separators and you link character strings and separators to form a source 
program. 


Table 2-1 shows the COBOL74 character set. 


Table 2—1. Character Set 


Character Meaning Character Meaning 


0 through 9 Digit . A through Z Letter 
Space or blank Plus sign 
Minus sign or hyphen Asterisk 
Virgule, or slash Equal sign 
Dollar sign | Comma or decimal point 
Semicolon ; Period or decimal point 
Quotation mark Left parenthesis 
Right parenthesis _ Greater than sign 


Less than sign Commercial at sign 


ft Unisys extension 
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Separators 


A separator is a string of one or more punctuation characters. You can link a separator 
with another separator or with a character string. A character-string must be linked to a 
separator. Table 2~2 lists all the separators and the rules governing them. 


Table 2-2. Meanings of Separators 


Explanation 


Separator 


(space) Spaces can precede or follow all other separators. Special rules for spaces are as 


follows: 
e Aspace is required before the opening pseudotext delimiter. 


e Aspace that precedes the ending quotation mark of a nonnumeric literal is 
considered to be part of the literal. 


e Aspace that follows the opening quotation mark of a nonnumeric literal is 
considered to be part of the literal. 


Periods mark the end of a COBOL74 entry. A period is always treated as a 
separator when it is followed by a space. In‘a Unisys extension, a period does not 
need to be followed by a space in most cases. tHowever, Unisys recommends that 
the period always be followed by a space when it is used as a separator character. 
This practice prevents problems in those environments in which the space is 
required but not encountered. 


oe Commas and semicolons delimit clauses. A comma or a semicolon is always 
treated as a separator when it is followed by a space. In a Unisys extension, they 
do not need to be followed by a space in most cases.t However, Unisys 
recommends that the comma and semicolon always be followed by a space when 
they are used as a separator character. This practice prevents problems in those 
environments in which the space is required but not encountered. 


() Left and right parentheses delimit subscripts, indexes, arithmetic expressions, or 
conditions. They must appear in balanced pairs. 


a Quotation marks delimit nonnumeric literals. They must appear in balanced pairs. 
If the literal is continued on another line, you need to enter another quotation 
mark as the first nonblank character in area B. An opening quotation mark must 
be preceded immediately by a space, left parenthesis, (comma, or semicolont ). 
A closing quotation mark must be followed immediately by a space, comma, 
semicolon, period, or right parenthesis. 


Pseudotext delimiters set off pseudotext. They must appear in balanced pairs. An 
Opening pseudotext delimiter must be preceded by a space. A closing pseudotext 
delimiter must be followed by a space, comma, semicolon, or period. 


Commercial at signs delimit undigit literals. An opening @ character must be 
preceded immediately by a space, comma, semicolon, or left parenthesis; a 
closing @ character must be followed immediately by a space, comma, 
semicolon, period, or right parenthesis. 


NC"t NC" characters precede a Kanji literal. A quotation mark follows the Kanji literal. 


+t Unisys extension 
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Any punctuation character that you use in a PICTURE character string or numeric 
literal is considered to be part of the PICTURE character string or numeric literal 
rather than a punctuation character. You delimit PICTURE character strings by spaces, 
commas, semicolons, or periods. 


The rules established for the formation of separators do not apply to the characters 
in nonnumeric literals, comment-entries, or comment tines. When you are coding 
nonnumeric literals, comment-entries, or comment lines, you can use the complete 
character set of the computer, not just the COBOL74 character set. 


Character Strings 


A character string is a set of one or more characters delimited by separators that form 
one of the following: 


e Word 
e Literal 
e PICTURE character string 


e Comment-entries 


See Also 
e For information about the various types of COBOL words, refer to “Word Types” 
later in this section. 


e For definitions and examples of the various types of literals you can use in a COBOL 
. program, refer to “Literals” later in this section. 


e For information about PICTURE character strings in the PICTURE clause, refer to 
Section 7, “DATA DIVISION.” 


e Refer to Section 1, “Program Structure,” for information about comment-entries. 
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Word Types 
A COBOL word is a character string that forms one of the following: 


e Reserved word — 

e Context-sensitive keyword 

e Application-specific keyword 

e System-name 

e User-defined word 

You can use a given COBOL word in your program as both a system-name and a 


user-defined word, or as both a system-name and a reserved word. You cannot use a 
reserved word as a user-defined word. 


Reserved Words 


A reserved word is a COBOL74 word that has a specific meaning to the compiler. 
For example, MOVE is a reserved word that directs the compiler to perform a move 
operation. 


A reserved word is a word that is reserved by the compiler and that you cannot use as 
a user-defined word anywhere in the source program. No exceptions exist for specific 
divisions, sections, or statements. Reserved words are used in the following six ways: 


e Asconnectives that qualify data, link two or more operands in a series, or link logical 
operators to form conditions — 


e As figurative constants that associate names to values that you commonly use in a 
source program 


e As keywords that are verbs or other required pieces of a syntax 
e As optional words that increase the readability of your program 


e As special registers that are compiler-generated, read-only storage areas that 
provide you with access to specific COBOL74 features 


e As special-character words that indicate arithmetic or relational operations 


See also 


For a complete list of reserved words in Unisys COBOL74, refer to Appendix B, 
“Reserved Words and Keywords.” 
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Connectives 
Connectives are reserved words that you can use in any of the following two ways: 


e Asa qualifier to associate a data-name, a condition-name, a text-name, or a 
paragraph-name with its qualifier. Examples of qualifier connectives are OF or IN. 


e As logical connectives to form conditions. Examples of logical connectives are AND 
and OR. 


Figurative Constants 


Figurative constants are reserved words that act as literals for values you might 
commonly use in a source program. These reserved words make your programming task 
easier by relieving you of the burden of assigning names to specified constant values. 
You can use a figurative constant wherever a literal can be used. For example, a MOVE 
SPACES TO data-name statement fills the data-name with spaces. The only figurative 
constant that acts as a numeric literal is the ZERO (ZEROS, ZEROES) figurative 
constant, and then only when you use it in a context that requires a numeric literal. 


You can use figurative constants in the following types of statements: 


e In MOVE and IF statements for moving and comparing data items 

e In DISPLAY and STOP statements for displaying one character 

e InSTRING and UNSTRING statements for manipulating one character 
Figurative constants increase the readability of your program. The singular and plural 
forms of figurative constants are equivalent and interchangeable. Each figurative 


constant is a distinct word, except for the ALL literal constant, which is two distinct 
words. 
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The individual figurative constants are described in Table 2-3, 


Table 2-3. Figurative Constants 


Figurative Constant Explanation | . i 


ZERO, ZEROS, Represents numeric O or one or more of the alphanumeric character 
ZEROES 0, depending on context. : 


SPACE, SPACES Represents one or more of the alphabetic character space from the 
character set of the computer. . 


HIGH-VALUE, Represents the alphanumeric character or characters that occupy 
HIGH-VALUES - the last position in your program's collating sequence. If you specify 
a collating sequence in the SPECIAL-NAMES paragraph, the 
HIGH-VALUE figurative constant represents the character or 
characters that occupy the last position in the collating sequence 
that you specify. This figurative constant may produce unexpected 
results when used with the system default ccsversion in the 
SPECIAL-NAMES paragraph. For more information, see 
“SPECIAL-NAMES” in Section 5, “ENVIRONMENT DIVISION.” 


LOW-VALUE, Represents the alphanumeric character or characters that occupy 

LOW-VALUES the first position in your program's collating sequence. If you specify 
a collating sequence in the SPECIAL-NAMES paragraph, the 
LOW-VALUE figurative constant represents the character or 
characters that occupy the first position in the collating sequence 
that you specify. This figurative constant may produce unexpected 
results when used with the system default ccsversion in the 
SPECIAL-NAMES paragraph. For more information, see 
“SPECIAL-NAMES” in Section 5, “ENVIRONMENT DIVISION.” 


QUOTE, QUOTES Represents one or more alphanumeric quotation mark characters. 
You can use this figurative constant to avoid using a quotation mark 
within a literal. For example, MOVE QUOTE TO OUT-LINE 
Causes a quotation mark to be printed. You cannot use QUOTE or 
QUOTES to bound a nonnumeric literal. For example, QUOTE XYZ 

QUOTE is incorrect as a way of stating the nonnumeric literal "XYZ". 


ALL literal Represents a continuous sequence of any alphanumeric literal. The 
literal part of the figurative constant must be a nonnumeric literal or 
a figurative constants other than ALL. When you use a figurative 
constant other than ALL as the literal, the word ALL is redundant. 
For example, MOVE ALL SPACES is equivalent to MOVE SPACES. 
You might want to retain the word ALL to improve the readability of 
your program. 
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When a figurative constant represents a string of one or more characters, the compiler 
determines the length of the string from context according to the following rules. 


e When a figurative constant is moved to or compared with another data item, the 
compiler repeats the string of characters specified by the figurative constant, 
character by character, until the receiving string has as many characters as the 
associated data item. The compiler independently completes the character repetition 
before it applies any JUSTIFIED clause that is associated with the data item. 


e When you compare the alphanumeric figurative constant HIGH-VALUE, 
LOW-VALUE, or QUOTE with a numeric data item in a relation condition, the 
compiler uses the rules for nonnumeric comparison. 


e When you move an alphanumeric figurative constant HIGH-VALUE, LOW-VALUE, 
or QUOTE to a numeric or numeric-edited data item, the compiler uses the rules 
for moving an alphanumeric item to a numeric or numeric-edited item; that is, 
the results are the same as if an alphanumeric data item contained the figurative 
constant value in all its character positions. The compiler moves the data as if 
the figurative constant was an unsigned numeric integer; therefore, it converts 
nonnumeric characters into numeric characters. For example, it converts the 
LOW-VALUE EBCDIC character to EBCDIC 0, the HIGH-VALUE EBCDIC 
character to EBCDIC 9, and the EBCDIC QUOTE character to EBCDIC 9. 


e When the figurative constants ZERO, SPACE, HIGH-VALUE, or LOW-VALUE are 
move to or compared with a Kanji data item, the compiler represents the actual 
character associated with each figurative constant as one or more of the Kanji 
characters. 


Examples 


The following example initializes a value in the WORKING-STORAGE SECTION to 
three zeros. 


77 NUMBER-OF-GUESTS PIC 9(3) VALUE ZEROS 


The next example uses LOW-VALUE and HIGH-VALUE to process an End-Of-File 
condition. 


77 EOF-FLAG PIC X VALUE LOW-VALUE 


READ GUEST-FILE AT END 
MOVE HIGH-VALUE TO EOF-FLAG. 
IF EOF-FLAG EQUAL TO HIGH-VALUE ... 


v 


The next example uses ZERO and SPACES for compare and move operations. 


IF NUMBER-OF-GUESTS EQUAL TO ZERO 
MOVE SPACES TO GUEST-LAST-NAME. 


8600 0296-000 | 27 


Language Elements 


The next example uses the ALL literal figurative constant ina MOVE ALL literal TO 
data-item statement. The first column shows the value of the literal, the second column 
shows the size of the data item designated as the receiving field, and the third column 
shows the value of that data item after the MOVE statement completes. 


Contents of 


Receiving Field Receiving Field 
ALL Literal -  $ize in Characters after MOVE 
ALL "ABC" 7 _ ABCABCA 
ALL "3" 5 . 33333 
ALL "HI-LO" 12 HI-LOHI-LOHI 
ALL "LIMIT" 4 LIMI 


The next example shows that the figurative constant ALL is redundant when used with 
a figurative constant. 


Contents of 


Figurative Receiving Field Receiving Field 
Constant Size in Characters after MOVE 
QUOTES 3 = 
ALL QUOTES 3 sa 

See Also 


e For information about specifying a collating sequence, refer to “OBJECT- 
COMPUTER” and “SPECIAL-NAMES” in Section 5, “ENVIRONMENT 
DIVISION.” 


e Refer to “MOVE” in Section 9, “PROCEDURE DIVISION Statements,” for 
information about rules for moving data. 


Keywords and Optional Words 


A keyword is a word that is required by the context in which it appears. In the format 
notation, keywords are uppercased and underlined. There are the following three kinds 
of keywords: 

e Verbs, such as ADD, READ, and MOVE 

e Functional words, such as NEGATIVE and SECTION 

e Other words that appear in statement and entry formats 

Optional words are reserved words that increase the readability of your program. They 


do not affect the execution of your program. In the format notation, they appear as 
uppercase words that are not underlined. 
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Example _ 


In the following example, RECORD is a keyword, CONTAINS and CHARACTERS 

are optional words, TO is a keyword required when the integer-1 option is used, and 

DEPENDING and ON are keywords required when the DEPENDING ON option is 
-used. Data-name is a user-defined word rather than a keyword, but if the DEPENDING 

ON option is present, the data-name user-defined word must appear too. Likewise, if . 

data-name is present, DEPENDING ON must appear too. . 


RECORD CONTAINS | integer-1 TO | integer-2 CHARACTERS 


[ DEPENDING ON data-name | 


See Also 


Refer to Appendix A, “General Format Notation,” for a full explanation of the format 
notation. 


Special Registers 


Special registers are compiler-generated, read-only storage areas that primarily give 
access to information produced with the use of specific COBOL74 features. 


Table 2-4 explains each of the special registers. . 


Table 2-4. Special-Register Definitions 


Register Explanation 


Contains the system date formatted as year of century, month of 
year, and day of month. DATE is an an unsigned, 6-digit, elementary 
numeric integer. For example, July 1, 1990, is expressed as 
900701. 


Contains the system date formatted as the year of century followed 
by the number of days since the beginning of the year. DAY is an 
unsigned, 5-digit, elementary numeric integer. For example, July 1, 
1990, is expressed as 90183. 


DEBUG-ITEM Provides information about the conditions that caused execution of a 
debugging section. Each execution of a debugging section has the 
special register DEBUG-ITEM associated with it. 


continued 
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Table 2-4. Special-Register Definitions (cont.) 


Register Explanation 


Contains the elapsed time after midnight based on a 24-hour clock 
in hours, minutes, seconds, and hundredths of a second. TIME is an 
unsigned, 8-digit, elementary numeric integer. For example, 2:41 
p.m. is expressed as 14410000. The maximum value of TIME is 
23595999. 


TIMERT Represents the number of 2.4-microsecond intervals since midnight. 
TIMER is a single, unsigned 11-digit, numeric integer. It is 
composed of the current value of the computer's interval timer. 


TODAYS-DATEt Represents the date as the month of the year, followed by the day of 
the month, followed by the year of the century. TODAYS-DATE is a 
6-digit, unsigned, elementary numeric integer. For example, July 1, 
1990, is expressed as 070190. 


TODAYS-NAMEt Provides the current day of the week. TODAYS-NAME is an 
elementary, 9-character, alphanumeric item. If the day of the week. 
is less than nine characters long, it is left-justified in the 9-character 
area provided, with space-fill on the right. 


LINAGE-COUNTER Contains at any time the number of lines advanced within a printed 
page. LINAGE-COUNTER is a fixed data-name for a line counter 
suitable for computation. It is generated by the presence ofa 
LINAGE clause in a file description (FD). The implicit class of a 
LINAGE-COUNTER is numeric. No data item is referenced; it is 
treated as a LINENUMBER attribute for purposes of retrieval. The 
compiler automatically supplies one LINAGE-COUNTER for each file 
in the FILE SECTION that has a LINAGE clause in its FD entry. 


LINE-COUNTER Provides the vertical position in a report. LINE-COUNTER is a fixed 
data-name for a line counter suitable for computation. It is 
generated for each report description (RD) in the REPORT SECTION. 
The compiler automatically provides one LINE-COUNTER register for 
each report in the RD entry. 


PAGE-COUNTER Provides page numbers within a report group. PAGE-COUNTER is a 
fixed data-name for a page counter suitable for computation. It is 
. generated for each report-description (RD) entry in the REPORT 
SECTION. The compiler automatically supplies one PAGE-COUNTER 
for each report that has the word PAGE-COUNTER as a source data 
item in a RD entry. 


+ Unisys extension 


Special-Character Words 
Special characters are reserved words used to indicate the arithmetic operations of 


addition, subtraction, multiplication, division, and exponentiation and the relational 
operations of comparing less than, greater than, and equal to conditions. 
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Table 2—5 shows the meaning of each special-character word. 


Table 2-5. Special-Character Words 


| Character Meaning 


Arithmetic Operator Plus sign 
Minus sign 
Multiplication 
Division 


Exponentiation 


Relation Character Less than sign 


Greater than sign 


Equals sign 


Context-Sensitive Keywords 


A context-sensitive keyword is a word that the compiler recognizes as reserved when it is 
used in a compiler-defined syntax. If you want to use that word as a user-defined word 
in another.place, the compiler recognizes it as a user-defined word in that context. 


See Also 


For a list of context-sensitive keywords, refer to Appendix B, “Reserved Words and 
Keywords.” 


Application-Specific Keywords 


An application-specific keyword is a word that is reserved by the compiler for the 
extent of the program. Application-specific keywords are used for applications 

such as internationalization and port files. You must specify that you are using 
application-specific keywords by using the RESERVE clause of the SPECIAL-NAMES 
paragraph in the ENVIRONMENT DIVISION. 


See Also 


e For information about using the RESERVE clause (a Unisys extension) to indicate 
that the compiler should treat certain keywords as application-specific, refer to 
“SPECIAL-NAMES?” in Section 5, “ENVIRONMENT DIVISION.” 


e For the list of application-specific keywords, refer to Appendix B, “Reserved Words 
and Keywords.” : 


8600 0296-000 2-11 


Language Elements 


System-Name 


Asystem-name is a word that you use to communicate with the sa environment. 
A system-name can be one of the following two types: 


A aciipiteemnnnns such as MICROA and A17, that identifies the computer on 
which the program is to be compiled or run. Computer-name is treated as a 
comment-entry. 


An implementor-name, such as ODT and SW1, that refers to a particular feature 
available with your system. 


The rules for forming a system-name are as follows: 


Make the system-name no more than 30 characters long. 


Select each character from the set of characters A through Z, 0 through 9, and the 


hyphen (—). 


Do not use the hyphen as the first or last character of a system-name. 


User-Defined Words 


A user-defined word is a word that you define to complete the format of a clause or 
statement. The rules for forming a user-defined word are as follows: 


Make the user-defined word up to 30 characters long. 

Select each character from the set of characters A through Z, 0 through 9, and the 
hyphen (-). 

Do not use the hyphen as the ie or last character of a word. 


Do not use a reserved word. 


Make sure that all user-defined words, except for level-numbers and 
segment-numbers, are unique. You can use qualification to ensure that a word 

is unique. Level-numbers and segment-numbers do not need to be unique. A 
given level-number or peument numer can be identical to a paragraph-name or a 
section-name. 


Include at least one alphabetic character in all user-defined words except 
paragraph-names, section-names, level-numbers, text-names, library-names, 
family-names, and segment-numbers. 
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Table 2-6 shows some of the user-defined words and explains how they are used in your 
program. : 


Table 2-6. User-Defined Words 


User-Defined Word Explanation 


Alphabet-name Assigns a name to a specific character set and collating sequence in 
the SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION. 


CD-name Assigns a name to a communication description (CD). 


Condition-name Assigns a name to a specific value, set of values, or range of values 
within a complete set of values that a conditional! variable can have. 
A conditional variable is a data item that can assume more than one 
value. The values that it can assume have condition-names 

assigned to them. A condition-name can also assign a name to a 

switch or device. 


Condition-names can be defined in the DATA DIVISION or in the 
SPECIAL-NAMES paragraph within the ENVIRONMENT DIVISION. 


You can use a condition-name as an abbreviation for a relation 
condition. A relation condition states that the associated conditional 
variable is equal to one of the set of values to which that 
condition-name is assigned. 


Data-name Names a data item described in a data-description entry. — 


Family-namet Identifies a family of disks on which a file resides. | 
File-name Names a file described in a file-description entry or a sort-merge file 


description (FD) entry in the FILE SECTION of the DATA DIVISION. 


Index-name Names an index associated with a specific table. 

Level-number Assigns a one- or two-digit number that shows the hierarchical 
position of a data item or a special property of a data-description 
entry. 

Library-name Names a COBOL library that is to be used in conjunction with the 
COPY statement by the compiler for a given source program 
compilation. 

Mnemonic-name Assigns a user-defined word to an implementor-name. These 
associations are established in the SPECIAL-NAMES paragraph of 
the ENVIRONMENT DIVISION. 

Paragraph-name Identifies and begins a paragraph in the PROCEDURE DIVISION. 


Paragraph-names are equivalent only if composed of the same 
sequence and number of digits and/or characters. 


Identifies a source program in the IDENTIFICATION DIVISION. 


Program-name 


Record-name Names a record described in a record-description (RD) entry in the 
DATA DIVISION. : 


+ Unisys extension . continued 
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Table 2~—6. User-Defined Words (cont.) 


User-Defined Word Explanation 


Report-name Names a Report Writer report described in a report-description (RD) 
entry in the DATA DIVISION. 


Routine-namet Identifies a procedure written in a language other than COBOL74. 


Section-name Names a section in the PROCEDURE DIVISION. Section-names are 
equivalent only if composed of the same sequence and number of 
digits and/or characters. | 


Segment-number Groups sections in the PROCEDURE DIVISION for the purposes of 
segmentation. 


Text-name Specifies the external identification of a file in the COBOL library. 


This manual also uses user-defined words that are not identified in Table 2-6 in order 
to clarify the meaning of a format notation. For example, an identifier for an event is 

‘ called an event-identifier. You can determine that a word is user defined if it appears in 
lowercase letters in the format notation. Some of the user-defined words described in 
Volume 2 are form-name, formlibrary-name, and group-list-name. 


See Also 


For information about qualification, refer to Section 6, “DATA Concepts.” — 


Literals 


A literal is a string of characters whose value is either the ordered set of characters of 
which the literal is composed or a reserved word that refers to a figurative constant. 


Every literal is one of the following five types: 


e Nonnumeric 
e Numeric 


e Floating point 


e Undigit 
e Kanji 
Nonnumeric 


A nonnumeric literal is a string of characters delimited on both sides by quotation marks. 
An example is "Month Year". You can use any allowable character in the character set of 
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the computer to form a nonnumeric literal. Nonnumeric literals are in the alphanumeric 
category. 


The rules for the formation of nonnumeric literals are as follows: 


Nonnumeric literals can be between 1 and 160 characters long. 


A single quotation mark is delimited by two contiguous quotation marks within a 
nonnumeric literal. Each embedded pair of contiguous quotation marks represents a 
single quotation mark character. 


Delimiting quotation marks are excluded from the value of the nonnumeric literal. 


Except delimiting quotation marks, all other punctuation characters within the 
literal are considered to be part of the nonnumeric literal. 


Any literals used for arithmetic computation must not be enclosed in quotes as 
nonnumeric literals. The literal "7.7" is a nonnumeric literal and is stored differently 
from the numeric literal 7.7 (not enclosed in quotes). 


_ Examples 


The following are examples of nonnumeric literals. The string on the left shows the 
literal as it appears in your source program. The string on the right shows the literal as 
it is stored by the compiler. 


Literal in Source Program Literal Stored by Compiler 
“ANNUAL DUES" ANNUAL DUES 

_ "(MILES/GALLON)" (MILES/GALLON) 
"-123.456" . -123.456 
"AB" A'B 
"LIMITATIONS" "LIMITATIONS" 


Numeric 


A numeric literal is a character string selected from the digits 0 through 9, the plus sign 
(+), the minus sign (—), and the decimal point. 


The rules for the formation of numeric literals are as follows: 


Aliteral can be between 1 and 28 digits long. 
A literal must contain at least one digit. 


A literal must not contain more than one sign character. Ifa sign is used, it must 
appear as the leftmost character of the literal. If the literal is unsigned, it is positive. 
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e Aliteral must not contain more than one decimal point. The decimal point is treated 
as an assumed decimal point and can appear anywhere within the literal except as 
the rightmost character. If the literal contains no decimal point, the literal is an 
integer. A literal that conforms to the rules for the formation of numeric literals, but 
is also enclosed in quotation marks, is a nonnumeric literal and is treated as such by 
the compiler. 


e The value of a numeric literal is the algebraic quantity represented by the characters 
in the numeric literal. Every numeric literal is in the numeric category. The size ofa 
numeric literal in standard data-format characters is equal to the number of digits 
that you specify. . 


Examples 


The following are examples of numeric literals: 


12345 
085 
+1.008 
8965 
7842.1 


Floating Point 


A floating-point literal is a string of characters that uses two numbers to represent one 
original number. The first number is called the mantissa. It has a value between 0 (zero) 
‘and nine. The second number is called the exponent. It represents the power of ten 

by which the first number is multiplied to obtain the original number. The format of a 
floating-point literal is as follows: 


mantissa E exponent 
For example, 8,765,432.1 is 8.7654321K6 in floating-point notation. 
The advantage of floating-point notation is that you can handle very small and very large 
numbers easily. You can use floating-point literals as alternatives to coding numeric 
literals. You should consider using floating-point literals with REAL and DOUBLE data 
items. 


The rules for the formation of floating-point literals are as follows: 


e The mantissa can be signed and must have one decimal point. 


e The exponent can be signed and must be an integer. 
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Table 2~7 shows the smallest and largest permitted values for single-precision and 
double-precision data items using floating-point literals. 


‘Table 2-7. Range of Values Permitted for Floating-Point Literals 


Type Smallest Permitted Value _ Largest Permitted Value 


Single 8.75811540203E-47 4.31359146674E68 
Double 1.93854585713758583355640E-29581 1.94882938205028079124469E29603 


Examples 


The following are examples of floating-point literals. 


1.E-48 

- .8823E29 

+. 0012345E-5 
+1.2E9500 

2.E48 

+123 .45678991234E29 


Undigit (Unisys Extension) 


An undigit literal is a string of characters that represents the hexadecimal equivalent 
_of an EBCDIC character. Each EBCDIC character is represented by two hexadecimal 
‘digits. This means there are always an even number of digits in an undigit literal. You 
might want to use an undigit literal to send control sequence messages to a remote 
terminal. 


The rules for the formation of undigit literals are as follows: 


e Delimit both ends of the literal with the commercial at sign (@) characters. 


e Select the characters from the hexadecimal digits 0 (zero) through 9 and the 
characters A through F. ; 


The compiler interprets the undigit literal as either a 4-bit numeric literal or an 8-bit 
alphanumeric literal. You determine the interpretation of the undigit literal by specifying 
the type of the data item to which the undigit literal is associated. An undigit literal 

is numeric if it appears in the VALUE clause associated with a COMPUTATIONAL 

item. An undigit literal is alphanumeric when the category of the associated data item is 
alphanumeric. 
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An undigit literal is interpreted as alphanumeric in the following cases: 
e Inthe VALUE clause associated with an alphanumeric, alphabetic, or group data 
item, or in the VALUE clause of condition-names associated with such items 


e Inthe MOVE statement, where the category of the receiving field is either 
alphanumeric or alphabetic 


e Inthe conditional expression of an IF, PERFORM, or SEARCH statement, where 
the category of the other relational operand is either alphanumeric or alphabetic 


e Inan INSPECT, STRING, UNSTRING, DISPLAY, STOP DISABLE, or ENABLE 


statement 


e Inthe ALL figurative constant 


You can use undigit literals for numeric destinations in the MOVE statement when your 
program meets all of the following criteria: 


e The usage of the destination is COMP 
e The picture string for the destination does not contain the symbols §, V, or P. 


e There is neither a SIGN clause nor a BLANK WHEN ZERO clause associated with 
the data item associated with the undigit literal. 


~ You can only use an undigit literal as described in the preceding paragraphs. No other 
uses are allowed. 


Examples 


The following are examples of undigit literals and their EBCDIC equivalents. 


Undigit literal EBCDIC Equivalent 
@0D@ CR (carriage return) 
@25@ LF (line feed) 


Kanji (Unisys Extension) 


A Kanji (National Character) literal is intended to be used with KANJI data items as an 
alternative to using standard nonnumeric literals. The general format for a Kanji literal 
is the following: 


NC" character-string " 
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The rules for the formation of a Kanji literal are as follows: 
e A Kanji literal is bounded on the left by the separator NC" and on the right by a 
quotation mark ("). 


e The character string contains a string of Kanji characters between the blank space 
after the first quotation mark and the blank space preceding the end quotation 
mark. The compiler recognizes the start and the end of a Kanji character string by 
means of the two blank spaces within the quotation marks. 


e Spaces are not allowed within the character string of Kanji characters. 


e A Kanji literal can be from 1 to 80 characters long. 


A Kanji literal occupies twice as much storage space as a literal that is not Kanji. 
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section 3 
File and Task Concepts 


To develop successful COBOL74 programs, you need to understand some concepts that 
underlie files and tasks. For example, to use files efficiently you need a knowledge of file 
attributes, file organization, and access mode. An understanding of the tasking concept 
includes knowledge of task attributes. 


Physical Aspects of a File 


File information describes both the physical aspects of the file and the sogical 
characteristics of the data in the file. 


The physical characteristics of a file describe the data as it appears on the input or 
output medium. This description refers to the grouping of the logical records within the 
physical limitations of the file medium. 


A physical record is a sivabal unit of data with a size and recording mode convenient 
for storing data on an input or output device of a particular computer. The size of a 
physical record is hardware dependent and has no direct relationship to the size of the 
information file contained on a device. 


The distinction between a physical record and a logical record, which is described next, is 
important. 


Logical Aspects of a File 


The conceptual characteristics of a file are the explicit definitions of each logical entity 
in the file. In a COBOL74 program, the input or output statements refer to one logical 
record. 


A COBOL logical record is related information that is uniquely identifiable and treated | 
as a unit. 


One or more logical records can be contained in a single physical record. In a mass 
storage file, however, one logical record could require more than one physical record. In 
this manual, references to records mean logical records unless the term physical record 
is specified. . 

The concept of a logical record is not restricted to file data. A logical record can also 


apply to the definition of working-storage. Thus, working-storage can be grouped into 
logical records and defined by a series of record-description entries. 


See Also 


Refer to “Levels” in Section 6, “Data Concepts,” for more information about records. 
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Assigning a File to a Device 


On A Series systems, the logical file mechanism supports access to remote and port files 
as well as to other devices. The devices to which a file can be assigned are specified in 
the SELECT clause of the ENVIRONMENT DIVISION. 


Remote Files 


Assignment of a file to a remote device enables the use of the logical file mechanism 
to access a family of terminal or station devices. This mechanism uses traditional 
file-handling methods rather than the specialized, data-communications handling 
methods of the communication module. 


Port Files 


User processes communicate across a network through the standard I/O file mechanism 
using a special kind of file called a port file. The program opens and closes port files 

just like other files. A user can communicate with a process by performing read and 
write operations to a port file. A port file is composed of one or more port subfiles, each 
of which can be connected to a different process. Communication between processes 

on the same host or system is effected by using port files without going through a 
network. In addition, there is a service associated with each port file. This service can 
be assigned with the SERVICE file attribute. For example, a user can set the SERVICE 
file attribute to BNANATIVESERVICE. 


A subfile provides a two-way, point-to-point, logical communication path between two 
programs. To establish this path, each program must describe the desired connection. 
This process is called matching. Each program describes its 6 matching properties by using 
file attributes. 


In the SELECT clause of the ENVIRONMENT DIVISION, the ACTUAL KEY clause 
specifies the subfile index of a port file. If the ACTUAL KEY value is 0 (zero), the 
OPEN statement opens all subfiles, the READ statement performs a nonselective read 
operation, the WRITE statement performs a broadcast write operation, and the CLOSE 
statement closes all opened subfiles associated with the port file. 


If no ACTUAL KEY clause is specified, the file must contain a single subfile, which is 
assumed to be the subfile in associated I/O statements. 


See Also 


The A Series I/O Subsystem Programming Guide provides more information about and 
an example of coding a port file application. 


File Attributes 


File attributes provide the capability for defining, monitoring, or changing file properties 
or attributes. 


3-2 | oe 8600 0296-000 


File and Task Concepts 


Note: File attributes provide you with access to functionality not otherwise 
available within the language. File attributes can also be used to 
declare and access files. When both a file attribute and standard 
COBOL74 syntax are available to accomplish a desired function, it is 

- always preferable to use the standard COBOL74 syntax. Changing 
the attribute can lead to unexpected results in cases when the attribute 
is also used or altered by the compiler. 


See Also 


e Refer to the I/O Subsystem Programming Guide for information about how to use 
file attributes. 


e Refer to the A Series File Attributes Programming Reference Manual for the details 
about a specific attribute. 


File-Attribute Identifiers 


File-attribute identifiers provide the ability to monitor, manipulate, define, or 
dynamically change any specific file attribute. 


The general format of the file-attribute identifier follows: 


ATTRIBUTE attribute-name ‘ar file-name [ (arithmetic-expression) | 


IN 


Explanation of Format 


The attribute-name is defined by the system. Examples of attribute names include 
FILETYPE, TITLE, and MAXRECSIZE. For more information on attribute names, see 
‘ the I/O Subsystem Programming Guide. 


Port Files 


A subfile index is required for accessing or changing attributes of a subfile of a port file. 
A subfile index must be an arithmetic expression. 


The arithmetic-expression option can be used only with a port file. The value of the 
expression specifies the subfile of the file that is affected. If the arithmetic-expression 
is not specified, the attribute of the port is accessed. If the arithmetic-expression is 
specified and its value is not 0 (zero), it specifies a subfile index and causes the attribute 
subfile to be accessed. If the arithmetic-expression is specified and its value is 0 (zero), 
then the arithmetic-expression causes causes the attribute of all subfiles to be accessed. 
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File-Attribute Categories 


A file attribute belongs to one of five categories, depending on the type of attribute-name 
specified in the file-attribute identifier. The five file-attribute categories are described in 
the following paragraphs. 


Alphanumeric File-Attribute Identifier 


Where allowed in syntax, an alphanumeric file-attribute identifier is similar to an 
elementary alphanumeric DISPLAY data item that has a size equal to the maximum 
size allowed for the specified attribute. The contents of the alphanumeric file-attribute 
identifier are left-justified with space-fill. Alphanumeric file-attribute identifiers are 
allowed as operands in relation conditions and'as sending operands in Format 1 MOVE 
statements. 


Numeric File-Attribute Identifier 


Where allowed in syntax, a numeric file-attribute identifier is similar to an elementary - 
numeric DISPLAY data item that represents a signed integer with eight decimal digits. 
Numeric file-attribute identifiers are allowed as operands in arithmetic expressions and 
as sending operands in Format 1 MOVE statements. Some numeric file attributes 
represent information about the number of areas, blocks, records, and so forth in the file. 
These attributes are “one relative” in that their value specifies the exact number of 
areas, blocks, records, and so forth in the file. 


Mnemonic File-Attribute Identifier 


Certain file attributes are associated with values that are best expressed as 
mnemonic-names because the magnitude of the actual value is unrelated to its meaning. 
Mnemonic file-attribute identifiers can appear as the subject of a mnemonic-attribute _ 
relation condition, with the name for one of the values associated with the specified 
attribute used as the object. The name for the attribute value must follow the reserved 
word VALUE as shown in the next example. 


_Mnemonic-attribute relation conditions are allowed in any conditional expression. The 
general format of a mnemonic-attribute relation condition follows: 


mnemonic-attribute-identifier IS | NOT | {Bawat mt 


a 
VA 


} mnemonic-attribute-value 
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Mnemonic-attribute relation conditions cannot be abbreviated. The names for the 
mnemonic-attribute values are system-names and are not necessarily reserved words. 
Boolean file attributes are considered mnemonic attributes in COBOL and are associated 
with the mnemonic-attribute values TRUE and FALSE. . ; 


Boolean File-Attribute Identifier 


These attributes are referenced in the same manner as numeric file-attribute identifiers. 
These attributes return the value 1 for TRUE and 0 for FALSE. 


Event File-Attribute Identifier 


The file attributes of the type EVENT are the same as the variables of the USAGE 
EVENT identifier. They can be used whenever an event-identifier is allowed. 


File Organization and Access Methods 


The organization of a file determines the access mode of that file. The organization can 
be sequential, relative, or indexed. 


Sequential Organization 


Sequential files are organized so that each record in the file except the first has a unique 
predecessor record, and each record except the last has a unique successor record. 
These predecessor/successor relationships are established by the order of the WRITE 
statements when the file is created. Once established, the predecessor/successor 
relationships do not change except when records are added to the end of the file. 


Records in a file with sequential organization can be accessed in the sequence established 
when the records were written to the file. A sequential mass storage file can be used for 
input and output at the same time. This feature enables a record to be read, updated, 
and returned with modifications to its original position for purposes of file maintenance. 


A file with sequential organization enables you to specify records in rerun points and 
share memory areas among files. 


Relative Organization 


Relative I/O enables you to access file records in either a random or a sequential manner. 
Each record in a relative file is uniquely identified by an integer value greater than 0 
(zero). The value is called the relative record number. It specifies the logical, ordinal 
position of the file record. 


Records are read from, and written to, the file based on the relative record number. 
For example, the tenth record is the record addressed by relative record number 10 
and occupies the tenth record area, whether or not record areas 1 through 9 have been 
written. 
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Indexed Organization 


Indexed I/O enables you to access file records in either a random or a sequential manner. 
Each record in an indexed file is cmauely identified by the value of one or more keys 
within that record. 


The record description of an indexed file includes one or more key data items, each 


associated with an index. The index provides a logical path to the data records, based on 
the contents of the record keys in each record. 


Current-Record Pointer 


The current-record pointer is a conceptual entity. It indicates to the program the next 
record to be accessed within a given file. 


For a file opened in the output mode, the current-record pointer concept has no meaning. 


For sequential files, the current-record pointer indicates the next record for OPEN and 
READ statements. 


For relative and indexed files, the current-record pointer indicates the next record for 
OPEN, READ, SEEK, and START statements. 


Task Attributes 


A task attribute is any one of a number of items that describe and control various 
aspects of the execution of a process. The program can access a task attribute by using a 
task identifier. The task identifier is a data item declared with task usage in the USAGE 
clause. 


A program can assign or change the value of a task attribute by uae the CHANGE 
statement or the MOVE statement. 


See Also 


e The syntax for setting task attributes is documented under the CHANGE statement 
_ in Section 9, “PROCEDURE DIVISION Statements.” 


e More information about tasking with COBOL74 is provided in the A Series Task 
Management Programming Guide. 


Task-Attribute Identifiers (Unisys Extension) 


Task-attribute identifiers are used to change or interrogate the task attributes of related 
processes in a synchronous or asynchronous processing environment. You should be 
familiar with the concepts of tasking, the task attributes, and their possible variations. 


3-6 8600 0296-000 


File and Task Concepts 


The general format of the task-attribute identifier follows: 


task-identifier | (subscript) | 
ATTRIBUTE attribute-name OF « MYSELF 


MYJOB 


Explanation of Format 


task-identifier 
A task-identifier can be attached to a program. For example, 


CHANGE ATTRIBUTE NAME OF PROG2 TO "OBJECT/TASK.". 


subscript 


The optional subscript is used when the task item is declared with an OCCURS clause. 
A maximum of one subscript is permitted. For example, 


CHANGE ATTRIBUTE DECLAREDPRIORITY OF PROG1 (1) TO 1. 


MYSELF 

The reserved word MYSELF is a compiler-supplied task item that enables a program to 
access its own task attributes. Thus, any attribute of a given task can be referenced 
within that task as ATTRIBUTE attribute-name OF MYSELF. For example, 


CHANGE ATTRIBUTE DECLAREDPRIORITY OF MYSELF TO 99. 


CHANGE ATTRIBUTE DECLAREDPRIORITY OF ATTRIBUTE PARTNER 
OF MYSELF TO 65. 


The second example illustrates another task running with a task that you are running. 


The PARTNER attribute refers to the other task and the example changes the 
DECLAREDPRIORITY of the other task. 


MYJOB 

The reserved word MYJOB is a compiler-supplied task item that enables a program to 
access the task attributes of its job. Thus, any attribute of a job can be referenced in any 
task of that job as ATTRIBUTE attribute-name OF MYJOB. For example, 


CHANGE ATTRIBUTE RESTART OF MYJOB TO 5. 
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Task-Attribute Types 


Task attributes of type EVENT can be used in place of any valid event-identifier 
(USAGE EVENT). 


Task attributes of type TASK are themselves task-identifiers of some other associated 
task. This type of attribute can be employed to access or ee the task attributes 
of the associated task. 


Task attributes of type POINTER accept or return an alphanumeric DISPLAY item. 


All other task attributes accept or return a numeric identifier, literal, arithmetic 
expression, or the value associated with a mnemonic. If the value is not in the 
permissible range for the attribute specified, an error occurs at compile time or at 
execution time. 


A task-attribute-mnemonic is a name associated with a constant value for an attribute 
that has a set number of predetermined possible values. 


The attribute names and their mnemonics are not treated as COBOL reserved words. 
They are reserved only within the context in which they are used and can be also used as 
data-names or procedure-names if they are not regular reserved words. Therefore, if a 
data-name has the same name as the system attribute mnemonic, the value assigned to 
the attribute by a CHANGE statement is determined by the use of the optional word 
VALUE. If the word VALUE is present, the attribute is set to the value of the system 
mnemonic. If the word VALUE is omitted, the attribute is set to the current value of 
data-name. 


interrogating Task Attributes 
You can interrogate a task attribute in any of the following ways: 


e By specifying a task attribute in the sending field of a MOVE statement. The 
following is an example: 


MOVE ATTRIBUTE PROCESSTIME OF PROG3 TO PRINT-P-TIME. 


When an attribute is moved into an area by a MOVE statement, the use of the 
receiving field must be consistent with the type of the attribute. Boolean attributes 
(those attributes having mnemonic values of TRUE or FALSE) return the number 0 
if FALSE or the number 1 if TRUE. Boolean or INTEGER attributes should be 
moved to a numeric receiving field. Type POINTER attributes should be moved to a 
nonnumeric receiving field. 
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e By making the task attribute the subject or object of a condition. The following is an 
example: 


IF ATTRIBUTE LOCKED OF PROG1 (1) = TRUE 
CHANGE ATTRIBUTE TASKVALUE OF PROG1 (1) TO -1. 


IF ATTRIBUTE NAME OF PROG2 = "X/Y/Z." 
PERFORM PRINT-ROUT INE 
UNTIL ATTRIBUTE STATUS OF PROG] (2) = VALUE SUSPENDED. 


e By using attributes with an implicit numeric class in DISPLAY statements. The 
following is an example: 


DISPLAY ATTRIBUTE STATUS OF PROG2 
ATTRIBUTE PROCESSTIME OF PROG2. 


e By using attributes with an implicit numeric class in place of any identifier in an 
arithmetic statement, except the receiving-field identifier. 


Task attributes can be tested against their associated attribute mnemonics. 


The program fragment of Example 3-1 sets the BDBASE option of the OPTION task 
attribute. Accessing specific options of the type OPTION task attribute requires use of 
mnemonic-attribute identifiers. The mnemonic-attribute identifiers represent specific 
bits in the type OPTION task attribute word. One way to access these bits is to use the 
Format 3 MOVE statement. ; 


11008 WORKING-STORAGE SECTION. 

11186 @1 OPTION-WORD PIC 9(11) BINARY. 

11288 @1 VALUE-ONE PIC 9(11) BINARY VALUE 1. 

113@@ PROCEDURE DIVISION. 

11490 P-1. | 

11506 MOVE ATTRIBUTE OPTION OF MYSELF TO OPTION-WORD. 
11608 MOVE VALUE-ONE TO OPTION-WORD [@:VALUE BDBASE:1]. 
11708 CHANGE ATTRIBUTE OPTION OF MYSELF TO OPTION-WORD. 


Example 3-1. Setting the BDBASE Option 


See Also 


For a description of the rules that govern move operations, refer to “MOVE” in 
Section 9, “PROCEDURE DIVISION Statements.” 
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IDENTIFICATION DIVISION 


The first division of the source program, the IDENTIFICATION DIVISION, provides 
identifying information about the source program such as the name of the program, the 
creation date, the compilation date, and other documentation information. 


With the exception of the DATE-COMPILED paragraph, the entire IDENTIFICATION 
DIVISION is copied from the input source program and listed on the output listing. 


The general format of the IDENTIFICATION DIVISION is as follows: 


ID 


ne DIVISION. 


[ PROGRAM-ID. program-name. | 


[ AUTHOR. [comment-entry ] ...] 


[ INSTALLATION. [comment-entry ] ...] 


[ DATE-COMPILED. [ comment-entry ] ...| 
[ DATE-WRITTEN. [ comment-entry ieee 


[ SECURITY. [ comment-entry ]...] 


Note: Because the AUTHOR, INSTALLATION, DATE-WRITTEN, and © 
SECURITY paragraph headers have associated text consisting only 
of comment-entries, they are not further documented. 


Explanation of Format 


The IDENTIFICATION DIVISION must begin with the reserved words 
IDENTIFICATION DIVISION or ID DIVISION followed by a period and a space. 
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ID DIVISION is a synonym for IDENTIFICATION DIVISION. (The reserved word ID is 
a Unisys extension.) . | 


The comment-entry can be any combination of characters from the character set of the 
computer. The continuation of the comment-entry by the use of the hyphen in the 
indicator area is not permitted; however, the comment-entry can be contained in one or 
more lines. 


Example 4~1 shows coding of the IDENTIFICATION DIVISION. 


IDENTIFICATION DIVISION. 


PROGRAM-ID. GENERAL UPDATE. 
AUTHOR. JOHN SMITH. 
INSTALLATION. MISSION VIEJO. 

DATE WRITTEN. — SEPTEMBER 18, 1984. 
DATE COMPILED. SEPTEMBER 15, 1984. 
SECURITY. FOREVER. 


Example 4-1. Coding the IDENTIFICATION DIVISION 


PROGRAM-ID Paragraph 


The PROGRAM-ID paragraph gives the name by which a program is identified. The 
general format is as follows: 


PROGRAM-ID. program-name. 


Explanation of Format 

The program-name identifies the source program and all listings pertaining to a 
particular program. The program-name must conform to the rules for formation of a 
user-defined word. 


The following describes the different uses of the program-name: 


Value of FEDLEVEL 

Compiler Option Use of Program-name 

<5 The program-name is treated as a comment. 

=5 The program-name is the entry-point name when the program is 

used as a library. If a library program does not use the 
PROGRAM-ID paragraph to designate an entry-point name, the 
entry-point name is PROCEDUREDIVISION. 
‘See Also 


Refer to Section 15, “Libraries,” for more information about creating a library. 
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- DATE-COMPILED Paragraph 


The DATE-COMPILED paragraph provides the compilation date in the 
IDENTIFICATION DIVISION source program listing. 


The general format of this paragraph is as follows: 


DATE-COMPILED. [ comment-entry ]... 


Explanation of Format 


The DATE-COMPILED paragraph causes the current date to be inserted during 
compilation. If a DATE-COMPILED paragraph is present, it is replaced during 
compilation with a paragraph of the following form: 


DATE-COMPILED. current-date. 


The current-date represents the date and time at which the compilation of the source 
program started. 

The comment-entry can be any combination of characters from the character set of the 
computer. The continuation of the comment-entry by use of the hyphen in the indicator 
area is not permitted; however, the comment-entry can be contained in one or more 
lines. 
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ENVIRONMENT DIVISION 


The second division of a source program, the ENVIRONMENT DIVISION, specifies a 
standard method of expressing aspects that depend on the physical characteristics of a 
specific computer. This division enables you to specify the compiling computer, the object 
computer, the files handled by the object program, and the I/O procedures to be used. 


The ENVIRONMENT DIVISION must be included in every COBOL source program 
and must begin with the reserved words ENVIRONMENT DIVISION followed by a 
period and a space. 


The ENVIRONMENT DIVISION consists of two sections: the CONFIGURATION 
SECTION and the INPUT-OUTPUT SECTION. 


The CONFIGURATION SECTION explains the characteristics of the source computer 
and the object computer. 


The INPUT-OUTPUT SECTION provides the information needed to control 
transmission and handling of data between external media and the object program. 


The following general format shows the overall syntax for the ENVIRONMENT 
DIVISION. The individual sections and paragraphs are further defined later in this 
section. 


The general format of the ENVIRONMENT DIVISION is as follows: 


ENVIRONMENT DIVISION. 


CONFIGURATION SECTION. 
[SOURCE-COMPUTER. source-computer-entry] 
[OBJECT-COMPUTER. object-computer-entry] 


[SPECIAL-NAMES. special-names-entry| 


UT-OUTPUT SECTION. 
FILE-CONTROL. {file-control-entry} ... 
[I-O-CONTROL. input-output-control-entry| 
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CONFIGURATION SECTION 


The CONFIGURATION SECTION lists the characteristics of the source computer and 
the object computer. This section is divided into the following three paragraphs: 


_@® The SOURCE-COMPUTER paragraph, which describes the computer configuration 
on which the source program is compiled 


e The OBJECT-COMPUTER paragraph, which describes the computer configuration 
on which the object program produced by the compiler is to be run 


e The SPECIAL-NAMES paragraph, which relates hardware names used by the 
COBOL compiler to the mnemonic-names in the source program 


SOURCE-COMPUTER 


The SOURCE-COMPUTER paragraph identifies the computer on which the program is 
to be compiled. 


The general format of this paragraph is as follows: 


SOURCE-COMPUTER. computer-name [ WITH DEBUGGING MODE ]. 


Explanation of Format 
The computer-name can be any single COBOL word. It is handled as a comment entry _ 


that describes the computer on which the source program is to be compiled. The 
computer-name is for documentation only. 


See Also 


For information on the effects of specifying DEBUGGING MODE, refer to Section 11, 
“Debugging.” 
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OBJECT-COMPUTER 


The OBJECT-COMPUTER paragraph identifies the computer on which the program is 
to be executed. 


The general format of this paragraph is as follows: 


OBJECT-COMPUTER. computer-name 


| WORDS 
| , MEMORY SIZE IS integer-1 | Gianacteas| | 
MODULES 


| , DISK SIZE IS integer-2 iaeoat \ 


MODULES 
[ , STACK SIZE IS integer-3 | 
[ , CODE SEGMENT-LIMIT IS integer-4 [ WORDS ] | 
[ ,SEGMENT-LIMIT IS segment-number | 


[ , PROGRAM COLLATING SEQUENCE IS alphabet-name |. 


Explanation of Format 


computer-name 


The computer-name is a system-name that identifies the hardware for which object 
code is to be generated. A valid OBJECT-COMPUTER system-name can be any single 
COBOL74 word. It is treated as a comment. 


MEMORY SIZE 


The MEMORY SIZE clause is used only in conjunction with the SORT statement. 

The SORT statement can also specify MEMORY SIZE and takes precedence over the 
OBJECT-COMPUTER paragraph. When MEMORY SIZE is not specified in either the 
SORT statement or the OBJECT-COMPUTER paragraph, a default memory size of 
12,000 words is assumed. If this option is used and a SORT statement does not appear 
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in the program, the option is ignored. One module of memory is equivalent to 16,384 
words of memory. . 


DISK SIZE (Unisys Extension) 


The DISK SIZE clause is used only in conjunction with the SORT statement. If this 
option is omitted in a sort program, DISK SIZE is assumed to be 900,000 words. If this 
option is used and a SORT statement does not appear in the program, the option is 
ignored. One module of disk is equivalent to 1.8 million words of disk. 


STACK SIZE (Unisys Extension) 


The STACK SIZE clause is for documentation purposes only. 


CODE SEGMENT-LIMIT (Unisys Extension) 


The CODE SEGMENT-LIMIT clause specifies the value for the size of an object-code 
segment in words. During the code-generation process, when the compiler completes the 
code for a paragraph or section, it ends the current segment and starts a new segment if 
the size of the current segment exceeds the target value. 


Integer-4 must be in the range 256 through 7000. If the CODE SEGMENT-LIMIT 
clause is not specified, the defauit segment size is 1500 words. 


For information about the SEGMENT-LIMIT clause, refer to Section 10, 
“Segmentation.” 


PROGRAM COLLATING SEQUENCE 


If the PROGRAM COLLATING SEQUENCE clause is specified, the collating sequence 
associated with alphabet-name is used to determine the truth value of any nonnumeric 
comparisons that are explicitly specified in relation or condition-name conditions or 

implicitly specified by the presence of a CONTROL clause in a report-description entry. 


For localization purposes, the program can specify the PROGRAM COLLATING 
SEQUENCE clause and a CCSVERICN collating sequence associated with an 
alphabet-name. In this case, the truth value of the alphabetic characters that are 
explicitly specified in the class condition do not always consist entirely of the characters 
A through Z and the space. The class of alphabetic characters is determined based on 
the system collating sequence when the CCSVERSION collating sequence is specified. 


If the PROGRAM COLLATING SEQUENCE clause is not specified, the EBCDIC 
collating sequence is used. If the PROGRAM COLLATING SEQUENCE clause is . 
specified, the program-collating sequence is the collating sequence associated with the 
alphabet-name specified in that clause. 


The PROGRAM COLLATING SEQUENCE clause is also applied to any nonnumeric 


merge or sort keys, unless the COLLATING SEQUENCE phrase of the respective 
MERGE or SORT statement is specified. . 
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See Also 


For information about specifying a collating sequence using the internationalization 
features, refer to Section 16, “Internationalization.” 


SPECIAL-NAMES 


The SPECIAL-NAMES paragraph enables you to do the following: 


Supply a name for a channel number, a switch, or the Operator Display Terminal 
(ODT) 


Supply a name for a character code set or collating sequence 
Specify a default sign position (Unisys extension) 


Designate a set of words to be recognized as reserved words for a specified kind of 
application (Unisys extension) 


Define a currency sign in edited numeric data 
Specify the role of the comma and period in edited numeric data 


Rename a file title for binding purposes 


Volume 2 of this manual describes the SPECIAL-NAMES paragraph extensions for 
specific product interfaces. 


The general format for the SPECIAL-NAMES paragraph is as follows: 
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SPECIAL-NAMES. 


CHANNEL nn IS mnemonic-name-1 
ODT IS mnemonic-name-2 
switch-name [ IS mnemonic-name-3 | 
ON STATUS JIS condition-name-1 
[, OFF STATUS IS condition-name-2 | 
OFF STATUS IS condition-name-2 
([ , ON STATUS IS condition-name-1 ] 


EBCDIC 
ASCII 
STANDARD-1 
| NATIVE 
CCSVERSION [ literal-1 ] 


THROUGH). _ 
{wer je — ; i. 


{ALSO literal-4} ... 


, alphabet-name IS 


[ CURRENCY SIGN IS literal-5 ] 
[ DECIMAL-POINT IS COMMA ]_ 
[ , literal-6 IS mnemonic-name-4 | 


LEADING 
TRAILING 


, DEFAULT DISPLAY [ SIGN IS ] Vecaine 
[ SEPARATE CHARACTER ] 


LEADING } 
TRAILING 


, DEFAULT cour or | [ SIGN IS ] { 
{=o | 


COMPUTATIONAL 
[ SEPARATE CHARACTER ] 


[ RESERVE WORD LIST IS NETWORK CAPABLE | 
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Explanation of Format 


CHANNEL nn IS mnemonic-name 


The CHANNEL nn IS mnemonic-name clause relates a mnemonic-name to a channel 
_ number, where nn is an integer from 01 to 11. You can use the mnemonic-name in a 
WRITE or SEND statement. 


ODT IS mnemonic-name 


The ODT IS mnemonic-name clause associates a user-defined word with the operator 
display terminal (ODT). You can use the mnemonic name in an ACCEPT or DISPLAY 
statement. 


switch-name 


The switch-name can be SW1, SW2, SW3, SW4, SW5, SW6, SW7, or SW8. The program 
uses switches to communicate with the external environment. A switch has a value of 
either ON or OFF. You can define a condition-name for each value of the switch. You 

can then check the status of the switch by testing the condition-name. You can set the 
switch at program initiation time or through Work Flow Language (WF) using the task 
attributes SW1, SW2, SW3, SW4, SW5, SW6, SW7, and SW8. 


The IS mnemonic-name-3 clause associates a user-defined word with a switch-name. 


The ON STATUS IS phrase associates a condition-name with the ON status of a switch. 
The condition-name is TRUE when the switch is set and FALSE when the switch is not 
set. 


- The OFF STATUS IS phrase associates a condition-name with the OFF status of a 
switch. The condition-name is TRUE when the switch is not set, and FALSE when the 
switch is set. 


A condition-name designates a value for either the ON or OFF value of a switch. You can. 
associate one condition-name value with the ON status and another with the OFF status. 
You define the condition-name as a level-number 88 data item in the DATA DIVISION. 


alphabet-name IS 


The alphabet-name IS clause relates an alphabet-name to a collating sequence or 

character set. ‘The alphabet-name refers to a collating sequence when you use it 

in the PROGRAM COLLATING clause of the OBJECT-COMPUTER paragraph 

or the COLLATING SEQUENCE phrase of a MERGE or a SORT statement. The 

alphabet-name refers to a character code set when you use it ina CODE-SET clause of a 
. file-description entry. 


The ASCII or STANDARD-1 phrase identifies alphabet-name as the saieee sequence 


or the character code set defined in the American National Standard Code for 
Information Interchange, X3.4-1968. 
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The NATIVE phrase or EBCDIC phrase identifies alphabet-name as the native character 
code set or native collating sequence. The native character code set is the character code 
set associated with USAGE IS DISPLAY, EBCDIC. 


The Unisys standard translation tables for EBCDIC-to-ASCII and ASCII-to-EBCDIC 
translation determine the correspondence between characters of the ASCII character 
code set and characters of the EBCDIC character code set. 


If the CCSVERSION option is specified, then the character code set and the collating 
sequence identified with the alphabet-name is the system collating sequence. If the 
CCSVERSION phrase is specified without literal-1, the collating sequence identified 
with the alphabet-name is the internationalized system default collating sequence. If 
the CCSVERSION phrase is specified with literal-1, the collating sequence is the one 
identified by literal-1, provided that literal-1 is valid. The alphabet-name cannot be 
referred to ina CODE-SET clause. 


The CCSVERSION phrase can only be specified once. Only one CCSVERSION can be 
specified in a program. 


Literal-2 specifies the positional value of the character in the program collating sequence. 
A given character can be specified only once as a literal in an alphabet-name clause. The 
value of each literal specifies both of the following characteristics: 


e The ordinal number of a character within the native character set, if the literal is 
numeric. Numeric literals must be unsigned integers and must have values in the 
range 1 through 256. 


e The actual character within the native character set, if the literal is nonnumeric. If 
the value of the nonnumeric literal contains multiple characters, each character in 
the literal, starting with the leftmost character, is assigned a successive ascending 
position in the collating sequence being specified. 


The order in which the literals appear in the alphabet-name clause specifies, in ascending 
sequence, the ordinal number of the character within the collating sequence being 
specified. 


Any characters in the native collating sequence that you do not specify in the literal 
phrase assume a position greater than any of the characters that you do specify in the 
collating sequence being specified. The relative order within the set of these unspecified 
characters is unchanged from the native collating sequence. 


The character that has the highest ordinal position in the program-collating sequence 
specified is associated with the figurative constant HIGH-VALUE. If more than one 
character has the highest position in the program-collating sequence, the last character 
specified is associated with the figurative constant HIGH-VALUE. 


The character that has the lowest ordinal position in the program-collating sequence 
specified is associated with the figurative constant LOW-VALUE. If more than one 
character has the lowest position in the program-collating sequence, the first character 
specified is associated with the figurative constant LOW-VALUE. 
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Note: Using the internationalized system default ccsversion can produce 
unexpected results for the HIGH-VALUE and LOW-VALUE 
figurative constants. These unexpected results can occur when the 
program is run on a host with a system default ccsversion that differs 
from the ccsversion compiled into the program. In this case, the 
HIGH-VALUE and LOW-VALUE figurative constants will contain 
the values that are correct for the ccsversion compiled into the 
program. 


For example, if the program was compiled on a host with a system 
default ccsversion of SPANISH, but the program is run on a host 
with a default ccsversion of FRANCE, the HIGH-VALUE and 
LOW-VALUE constants define their values from the SPANISH 
ccesversion at compile-time, rather than from the FRANCE ccsversion. 


The THROUGH literal-3 phrase assigns successive ascending positions to the set of 
contiguous characters in the native character set, beginning with the character specified 
by the value of literal-1 and ending with the character specified by the value of literal-3. 
The set of contiguous characters can specify characters of the native character set in 
either ascending or descending sequence. The words THROUGH and THRU are 
equivalent. Each literal must be one character in length. 


The ALSO literal-4 phrase assigns literal-4 to the same position in the collating sequence 
as literal-1. 


CURRENCY SIGN IS literal-5 


The CURRENCY SIGN IS literal-5 clause assigns the symbol used to represent the 
currency symbol in the PICTURE clause. If your program does not specify a currency 
symbol, the program uses the dollar sign ($) as the currency symbol in the PICTURE 
clause. The literal must be a single character. The currency symbol cannot be any of the 
following characters: 


e Digits 0 through 9 
e Alphabetic characters A, B, C, D, L, B R, S, V, X, Z, and the space 
e The following special characters: 


* (asterisk) + (plus sign) 

— (minus sign) . (period) 

; (semicolon) ( (left parenthesis) 
) (right parenthesis) "(quotation mark) 
, (comma) (stroke) 

= (equal sign) | 
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DECIMAL-POINT IS COMMA 


The DECIMAL-POINT IS COMMA clause causes the comma to act as the decimal point 
and the period to represent the separator for thousands in the character string of the 
PICTURE clause and in numeric literals. For example, 1,000.00 changes to 1.000,00 with 
this option specified. 


literal-6 IS mnemonic-name-4 (Unisys Extension) 


_ The literal-6 IS mnemonic-name-4 clause associates a mnemonic-name with a valid 


program name. Literal-6 can be of the form AAA/BBB/CCC..., where each group of 
characters between two slashes is one directory of the program-name. A directory can 
have a maximum of 17 characters, and a file title can have a maximum of 14 directories. 
This clause is used for binding or tasking. | 


DEFAULT DISPLAY SIGN (Unisys Extension) 


The DEFAULT DISPLAY SIGN clause, a Unisys extension, specifies a default sign 


position for all signed DISPLAY data items. If you declare a signed data item in the 


DATA DIVISION and do not use the optional SIGN clause, the program uses the 


default sign for that type of data item. The use of the optional SIGN clause in the DATA 


DIVISION overrides the default sign specification in the SPECIAL-NAMES paragraph. 


DEFAULT COMPUTATIONAL SIGN (Unisys Extension) 


The DEFAULT COMPUTATIONAL SIGN clause, a Unisys extension, specifies a 
default sign position for all signed COMPUTATIONAL data items. If you declare a 
signed data item in the DATA DIVISION and do not use the optional SIGN clause, the 
program uses the default sign for that type of data item. The use of the the optional 
SIGN clause in the DATA DIVISION overrides the default sign specification in the 
SPECIAL-NAMES paragraph. 


RESERVE NETWORK (Unisys Extension) 


The RESERVE NETWORK clause tells the compiler to handle the network class of 
application-specific keywords as reserved words for the extent of the program. If the 
program does not include the RESERVE NETWORK option, then the program can 

use the network keywords as normal identifiers. If you need to use port files with 
OSINATIVE service, then you should include the RESERVE NETWORK option in your 
program in order for the compiler to recognize keywords like the RESPOND verb as 
reserved words. . 


See Also 


e For information about identifying a collating sequence, refer to 
“OBJECT-COMPUTER’” earlier in this section. 


e For more information about specifying a sign position, refer to “SIGN Clause” and 
“PICTURE Clause” in Section 7, “DATA DIVISION” and explanations of the 
LEADING and TRAILING options. . 
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e For more information on binding, refer to the A Series Binder Programming 
Reference Manual. 


e For definition of port files, refer to “Port Files” in Section 3, “File and Task 
-Concepts”. 


e For information on localizing a COBOL74 application, refer to Section 16, 
“Internationalization.” 


e For information on the RESERVE SEMANTIC clause and the DICTIONARY clause 
of the SPECIAL-NAMES paragraph, refer to Volume 2 of this manual. 


INPUT-OUTPUT SECTION 


The INPUT-OUTPUT SECTION contains the information needed to control 
transmission and handling of data between external media and the object program. If 
included, this section must begin with the reserved words INPUT-OUTPUT SECTION, 
followed by a period and a space. The INPUT-OUTPUT SECTION is divided into two 
paragraphs: 


e The FILE-CONTROL paragraph, which names and associates the file with external 
_ media 


e The I-O-CONTROL paragraph, which defines special control techniques to be used 
in the object program 
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FILE-CONTROL Paragraph 


The FILE-CONTROL paragraph enables you to do the following. 


5-12. 


Name each file. 


Identify the file medium. 
Specify hardware. 
Specify alternate I/O areas. 


Specify the organization of the file. 


The FILE-CONTROL paragraph is required in the INPUT-OUTPUT SECTION. You 
must include the reserved words FILE-CONTROL, followed by a period, a space, and the 


_ file-control entries. 


There are five formats for the file-control entries. These formats are used in the 


following ways: 


Format 


1 


2 
3 
4 


Explanation 

This format is used for sequential files. 
This format is used for relative files. 
This format is used for indexed files. 


This format is used for sort and merge 
files. 


. Refer to Volume 2 for information about 


the DICTIONARY-REFERENCE clause. 
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Sequential 1/0 


Your program must use Format 1 of the FILE-CONTROL paragraph if it is doing 
sequential I/O. 


Format 1: Sequential I/O 


LOCAL » 


; REFERENCE 
oni | | RECEIVED By { a 


SELECT REF 


[ OPTIONAL ] file-name 


DISK 
TAPE 
READER 
ASSIGN TO { PUNCH 
PRINTER 
REMOTE 
PORT 


. AREA 
; RESERVE integer-1 
| Ss integer Fee 


[ ; ORGANIZATION IS SEQUENTIAL | 


SEQUENTIAL 
RANDOM \ 


; ACCESS MODE IS { 


- |; ACTUAL KEY IS data-name-1 | 


[ ; FILE STATUS IS data-name-2 ] . 
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Explanation of Format 1 


SELECT 


The SELECT clause declares each file described in the DATA DIVISION. Each file 
described in the DATA DIVISION must be named once as a file-name in the SELECT 
clause. Each file specified in the SELECT clause must have a file-description (FD) 
entry in the DATA DIVISION. The SELECT clause must be the first clause in the 
FILE-CONTROL paragraph. The clauses that follow the SELECT clause can appear in 
any order. 


LOCAL (Unisys Extension) 


The LOCAL option is meaningful only for programs being compiled as procedures. The 
LOCAL option specifies that the file is a formal parameter for a procedure and can be 
named only in WITH and USING clauses in the declarative USE statement associated 
with the procedure. 


The LEVEL compiler option must be greater than 2 to use the LOCAL option. 


GLOBAL (Unisys Extension) 


The GLOBAL option is meaningful only for programs being compiled as procedures. The 
GLOBAL option specifies that the first record description must match, by name and | 
array type, a similar record description for the file in the host. For example, 


SELECT GLOBAL GFILE ASSIGN TO DISK. 
The GLOBAL compiler option has no effect on ENVIRONMENT DIVISION or FILE 


SECTION entries. The LEVEL compiler option must be greater than 2 to use the 
GLOBAL option. 


RECEIVED BY REFERENCE or RECEIVED BY REF (Unisys Extension) 


The RECEIVED BY REFERENCE option enables two or more programs to use the file 
with which this option appears. Either program can perform I/O to the file. The default 
is RECEIVED BY REFERENCE. 


This option is meaningful only if the file-name appears in the USING clause of the 
PROCEDURE DIVISION header. If the program does not have a RECEIVED BY 
REFERENCE clause, the compiler issues a warning when it encounters the file-name in 
the USING clause. 


The compiler issues a syntax error if the LOCAL and the RECEIVED BY REFERENCE 
clauses appear in the same file. 


RECEIVED BY REF is a synonym for RECEIVED BY REFERENCE. 
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OPTIONAL 


The OPTIONAL phrase specifies an input file that is optional. Specification is required 
for input files but not necessarily each time the object program is executed. 


ASSIGN 


The ASSIGN clause associates the named file with a storage medium. (ASSIGN TO 

REMOTE and ASSIGN TO PORT are Unisys extensions.) DISK specifies that mass 
storage is the storage medium of the file. You can more precisely specify the storage 
medium by using the file attribute mechanism (that is, the VALUE OF clause in the 

file-description entry) or by using a file equation. 


RESERVE 


The RESERVE clause enables you to specify the number of I/O areas to be allocated. 
If the RESERVE clause is specified, the number of I/O areas allocated is equal to the 
value of integer-1. Two areas are automatically supplied when the RESERVE clause is 
omitted. 


ORGANIZATION 


The ORGANIZATION clause specifies the logical structure of a file. The file 
organization is established when a file is created and cannot subsequently be changed. 
The default organization for a file is SEQUENTIAL. 


ACCESS MODE 


The ACCESS MODE clause specifies whether records in a sequentially organized file are 
to be accessed sequentially or randomly. You can specify random access for mass-storage 
files only. (RANDOM access is a Unisys extension.) 


The default mode of access is sequential. 


ACTUAL KEY (Unisys Extension) 


The ACTUAL KEY clause can be specified only for mass-storage, port, and remote files. 
Data-name-1 must be defined in the DATA DIVISION as an elementary numeric item 
that describes an unsigned integer. If the ACTUAL KEY clause is specified, the following 
rules apply: 


e For mass-storage files specifying an ACTUAL KEY, the value of the ACTUAL KEY 
data item specifies the logical ordinal position of the record in the file. 


e For port files, the value of the ACTUAL KEY data item specifies the subfile index of 
the port file. 


e For remote files, the value of the ACTUAL KEY data item saath the ordinal 
number of the station within the station list of the remote file. A zero value specifies 
all stations within the station list of the remote file. 
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The ACTUAL KEY clause must be specified for a port file that contains more than one 


subfile. 


FILE STATUS 


When the FILE STATUS clause is specified, the system moves a value into the data item 
specified by data-name-2 after execution of every statement that explicitly or implicitly 
references that file. This value indicates the status of execution of the statement. 
Data-name-2 must be defined in the DATA DIVISION as a two-character, alphanumeric 
data item and must not be defined in the FILE SECTION, the REPORT SECTION, or 
the COMMUNICATION SECTION. Data-name-2 can be qualified. 


See Also 


e For information about status values, refer to “I/O Status” later in this section. 


e For more information about sequential I/O, refer to “File Organization and Access 
Methods” in Section 3, “File and Task Concepts.” 
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Relative 1/O 


Your program must use Format 2 when it is performing relative I/O. 


Format 2: Relative I/O 


LOCAL 
GLOBAL 


REFERENCE 


SELECT | REF 


| | RECEIVED BY { } filename 


ASSIGN TO DISK 


| ; RESERVE integer-1 en | | 
AREAS 


; ORGANIZATION IS RELATIVE 


SEQUENTIAL | ,RELATIVE KEY IS data-name-1 ] 
; ACCESS MODE IS ¢ (RANDOM | 
Ree 


\ , RELATIVE KEY IS data-name-1 


[ ; FILE STATUS IS data-name-2 ]. 


Explanation of Format 2 


SELECT 


The SELECT clause declares each file described in the DATA DIVISION. Each file 
described in the DATA DIVISION must be named once as a file-name in the SELECT 
clause. Each file specified in the SELECT clause must have a file-description (FD) 
entry in the DATA DIVISION. The SELECT clause must be the first clause in the 
FILE-CONTROL paragraph. The clauses that follow the SELECT clause can appear in 
any order, except that the RELATIVE KEY clause must follow the ACCESS MODE 
clause. 
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LOCAL (Unisys Extension) 


The LOCAL clause is meaningful only for programs being compiled as procedures. The 
LOCAL clause specifies that the file is as a formal parameter for a procedure and can be 
named only in WITH and USING clauses in the declarative USE statement associated 
with this procedure. oe 


The LEVEL compiler option must be greater than 2 to use the LOCAL clause. 


GLOBAL (Unisys Extension) 


The GLOBAL clause is meaningful only for programs being compiled as procedures. The 
GLOBAL clause specifies that the first record description must match, by name and 
array type, a similar record description for the file in the host. For example, 


_ SELECT GLOBAL GFILE ASSIGN TO DISK. 


The GLOBAL compiler option has not effect on ENVIRONMENT DIVISION or FILE 
SECTION entries. The LEVEL compiler option must be greater than 2 to use the 
GLOBAL option. 


RECEIVED BY REFERENCE or RECEIVED BY REF (Unisys Extension) 


The RECEIVED BY REFERENCE phrase enables two or more programs to use the file 
with which this option appears. Either program can perform I/O to the file. The default 
is RECEIVED BY REFERENCE. 


This option is meaningful only if the filename appears in the USING clause of the 
PROCEDURE DIVISION header. If the program does not have a RECEIVED BY 
REFERENCE clause, the compiler issues a warning when it encounters the file-name in 
the USING clause. 


The compiler issues a syntax error if the LOCAL and the RECEIVED BY REFERENCE 
clauses appear in the same file. 


RECEIVED BY REF is a synonym for RECEIVED BY REFERENCE. 


ASSIGN 


The ASSIGN clause associates the named file with a storage medium. DISK specifies 
that mass storage is the storage medium of the file. You can more precisely specify the 
storage medium by using the file attribute mechanism (the VALUE OF clause in the 
file-description entry) or through file equation. 


RESERVE | 
The RESERVE clause enables specification of the number of I/ O areas allocated. If the 


RESERVE clause is specified, the number of I/O areas allocated is equal to the value of _ 
integer-1. Two areas are allocated when the RESERVE clause is omitted. 
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ORGANIZATION 


The ORGANIZATION clause specifies the logical structure of a file. The file 
organization is established when a file is created and cannot subsequently be changed. 


The default file organization is sequential. 


ACCESS MODE 


When the ACCESS MODE is SEQUENTIAL, records in the file are accessed in the 
sequence dictated by the file organization. This sequence is the order of ascending 
relative record numbers of existing records in the file. All records stored in a relative 

file are uniquely identified by relative record numbers. The relative record number of a 
given record specifies the logical ordinal position of the record in the file. The first logical 
record has a relative number of 1, and subsequent logical records have relative record 
numbers of 2, 3, 4, and so forth. 


The default mode of access is sequential. 


The RELATIVE KEY. phrase is required when the access mode is dynamic or random. 
When the access mode is dynamic, records in the file can be accessed sequentially, 
randomly, or both, depending on the verbs used in the PROCEDURE DIVISION. 
Dynamic access is random by relative key except in the case of the READ NEXT 
statement, in which case the system updates the value of the relative key. 


If the access mode is random, the value of the RELATIVE KByY data item indicates the 
record to be accessed. 


_If a relative file is referenced by a START statement, the RELATIVE KEY phrase must 
be specified for that file. Data-name-1 must not be defined in a record-description (RD) 
entry associated with that file-name. Data-name-1 can be qualified. 


If the access mode is sequential, the system maintains the value of the relative key on all 
I/O operations. 


FILE STATUS 


When the FILE STATUS clause is specified, the system moves a value into the data item — 
specified by data-name-2 after execution of every statement that explicitly or implicitly 
references that file. This value indicates the status of execution of the statement. 
Data-name-2 must be defined in the DATA DIVISION as a two-character, alphanumeric 
data item and must not be defined in the FILE SECTION, the REPORT SECTION, or 
the COMMUNICATION SECTION. Data-name-2 can be qualified. 


See Also 


For information about status values, refer to “I/O Status” later in this section. 


8600 0296-000 ; | | | 619 


ENVIRONMENT DIVISION 


Indexed I/O 


Your program must use Format 3 if it is performing indexed I/O. 


Format 3: Indexed I/O 


LOCAL 
GLOBAL 


— 


REFERENCE 


| RECEIVED BY ie 


SELECT \ file-name 


ASSIGN TO DISK 


| s RESERVE integer-1 fear 


AREAS 
; ORGANIZATION IS INDEXED 


SEQUENTIAL 
; ACCESS MODE IS RANDOM | 
DYNAMIC 


; RECORD KEY IS data-name-1 


BINARY 
; COMPARISON IS { LOGICAL 
EQUIVALENT 


[ ; KEY-LENGTH IS integer-2] 


[ ; ALTERNATE RECORD KEY IS data-name-2 [ WITH DUPLICATES lees 


[ ; FILE STATUS IS data-name-3 | 


5-20 


8600 0296-000 


ENVIRONMENT DIVISION 


Explanation of Format 3 


SELECT 


The SELECT clause declares each file described in the DATA DIVISION. Each file 
described in the DATA DIVISION must be named once as a file-name in the SELECT 
clause. Each file specified in the SELECT clause must have a file-description (FD) 
entry in the DATA DIVISION. The SELECT clause must be the first clause in the 
FILE-CONTROL paragraph. The clauses that follow the SELECT clause can appear in 
any order. 


LOCAL (Unisys Extension) 


The LOCAL clause is meaningful only for programs being compiled as procedures. The 
LOCAL clause indicates that the file is a formal parameter for a procedure and can be 
named only in WITH and USING clauses in the declarative USE statement associated 
with this procedure. 


The LEVEL compiler option must be greater than 2 to use the LOCAL option. 


GLOBAL (Unisys extension) 


The GLOBAL clause is meaningful only for program being compiled as procedures. The 
GLOBAL clause specifies that the first record description must match, by name and 
array type, a similar record description for the file in the host. For example, 


SELECT GLOBAL GFILE ASSIGN TO DISK. 


The GLOBAL compiler option has no effect on ENVIRONMENT DIVISION or FILE 
SECTION entries. The LEVEL compiler option must be greater than 2 to use the 
GLOBAL option. 


RECEIVED BY REFERENCE or RECEIVED BY REF 


The RECEIVED BY REFERENCE or RECEIVED BY REF phrase, a Unisys extension, 
enables two or more programs to use the file with which this option appears. Hither 
program can perform I/O to the file. The default is RECEIVED BY REFERENCE. 


This option is meaningful only if the file-ename appears in the USING clause of the 
PROCEDURE DIVISION header. If the program does not have a RECEIVED BY 
REFERENCE clause, the compiler issues a warning when it encounters the file-name in 
the USING clause. | 


The compiler issues a syntax error if the LOCAL and the RECEIVED BY REFERENCE 
clauses appear in the same file. 


RECEIVED BY REF is a synonym for RECEIVED BY REFERENCE. 
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ASSIGN 
The ASSIGN clause associates the named file with a storage medium. DISK specifies 
that mass storage is the storage medium of the file. You can more precisely specify the 


storage medium by using the file attribute mechanism (the VALUE OF clause in the 
file-description entry) or through file equation. 


RESERVE 
The RESERVE clause enables you to specify the number of I/O areas allocated. If the 


RESERVE clause is specified, the number of I/O areas allocated equals the value of 
integer-1. Two areas are allocated when the RESERVE clause is omitted. 


ORGANIZATION 


The ORGANIZATION clause specifies the logical structure of a file. The file 
organization is established when a file is created and cannot be changed later. 


The default file organization is sequential. 


ACCESS MODE 


When the access mode is sequential, records in the file are accessed in the sequence 
dictated by the file organization. For indexed files, this sequence is the ascending order 
of record values within a given key of reference. 


If the access mode is random, the value of the record key data item indicates the record 


to be accessed. _ 


When the access mode is dynamic, records in the file can be accessed sequentially, 
randomly, or both. . 


The default mode of access is sequential. 


RECORD KEY 


The RECORD KEY clause specifies the prime record key for the file. The values of the 
prime record key must be unique among the file records. This prime record key provides 
an access path to records in an indexed file. This clause is required for indexed files. 


COMPARISON (Unisys Extension) 


The COMPARISON clause specifies the type of comparison to be performed when 
searching for the key. This clause is used only for internationalization purposes. A 
binary comparison uses the binary value of the key. If the program does not specify the 
type of comparison, it performs a binary comparison. 


A logical comparison uses the collating sequence value of the key. The collating sequence 


is the arrangement of members of a character set according to the ordering sequence 
values (OSVs) and the priority sequence values (PSVs). Elements occupy different code 
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positions, with elements having the same OSV differentiated by the PSV assigned to the 
code position. 


An equivalent comparison uses the ordering value of the key. The ordering sequence is 
the arrangement of members of a character set according to a predetermined scheme. 
Different elements can have the same ordering attribute. For example, you might want 
the equivalent uppercase and lowercase characters (a and A, b and B, and so on) to have 
the same ordering values. | 


KEY-LENGTH (Unisys Extension) 


The KEY-LENGTH option specifies the number of 8-bit characters the system uses 
when it stores a translated key value. The clause is used for internationalization only. 
Translated display data can require a larger storage area when including ordering and 
collating information. The KEY-LENGTH clause can be used with the prime record key 
or the alternate record key when the internationalization features are used. . 


If a key length is provided, the number of 8-bit characters used to store a translated key 
equals the value of integer-2. Otherwise, the length of the key item is used. Truncation 
of the stored key occurs if the key length value is too small. If the program specifies a 
system default ccsversion by coding the alphabet-name IS CCSVERSION clause without 
the literal-1 option in the SPECIAL-NAMES paragraph, that same ccsversion must be 
the system default ccsversion at run time. A run-time error occurs when opening the 
indexed file for output if the run-time ccsversion does not match the compiled ccsversion. 


ALTERNATE RECORD KEY 


An ALTERNATE RECORD KEY clause specifies an alternate record key for the file. 
This alternate record key provides an alternate access path to records in an indexed file. 


The data items referenced by data-name-1 and data-name-2 must each be defined as 
data items of the category alphanumeric or numeric within a record-description entry 
associated with that file-name. Neither data-name-1 nor data-name-2 can describe a | 
variable-size item. Data-name-1 and data-name-2 can be qualified. 


Data-name-2 cannot reference an item with the leftmost character position 
corresponding to the leftmost character position of an item referenced by data-name-1 or 
by any other data-name-2 associated with this file. 


The data descriptions of data-name-1 and data-name-2 and their relative locations within 
a record must be the same as those used when the file was created. The number of 
alternate keys for the file must also be the same as the number used when the file was 
created. 


The DUPLICATES phrase specifies that the value of the associated alternate record key 
can be duplicated within any of the zecords in the file. If the DUPLICATES phrase is 
not specified, the value of the associated alternate record key must not be duplicated 
among any of the records in the file. 
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FILE STATUS 

When the FILE STATUS clause is specified, a value is moved by the operating system 
into the data item specified by data-name-3 after execution of every statement that 
explicitly or implicitly references that file. This value indicates the status of execution of 
the statement. 

Data-name-3 must be defined in the DATA DIVISION as a two-character, alphanumeric 


data item and must not be defined in the FILE SECTION, the REPORT SECTION, or 
the COMMUNICATION SECTION. Data-name-3 can be qualified. 


See Also 


For information about status values, refer to “I/O Status” later in this section. 


Sort-Merge 


Your program must use Format 4 for files that are to be sorted or merged. 


Format 4: Sort-Merge 


SELECT file-name 


TAPES 


| DISK [ AND integer-1] re } 


ASSIGN TO 


Explanation of Format 4 


Each sort or merge file described in the DATA DIVISION must be named once, and only 
once, as a file-name in the FILE-CONTROL paragraph. Each sort or merge file specified 
in the file-control entry must have a sort-merge file-description entry in the DATA 
DIVISION. 


Because the file-name represents a sort or merge file, only the ASSIGN clause is 
permitted to follow the file-name in the SELECT statement. The ASSIGN clause 
associates the named sort or merge file to a storage medium. 


The options following the SORT and MERGE clauses in Format 4 are Unisys extensions. 
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If TAPE or TAPES is specified, the primary work medium is still DISK. TAPE or TAPES 
can be specified to contain any overflow. If integer-2 is not specified, the default number 
of tapes is three. Integer-1 and integer-2 must have values in the range 3 through 8. 
When DISK is specified, mass storage is the primary work medium. TAPE or TAPES 


can be specified to contain any overflow. If integer-1 is not specified, three tapes are 
assumed. 


1-O-CONTROL 
The I-O-CONTROL paragraph specifies the following: 


e The points at which rerun is to be established 
e The memory area to be shared by different files 


e The location of files on a multiple-file reel 


The general format of this paragraph is as follows: 


I-O-CONTROL. 


[ ; RERUN [ ON DISK | EVERY integer-1 RECORDS OF file-name-2 | ... 


[ ; SAME [ RECORD ] AREA FOR file-name-3 {, filename-4}...] ... 


; MULTIPLE FILE TAPE CONTAINS file-name-5 | POSITION integer-3 | 
[ , file-name-6 [ POSITION integer-4 | ] ... 


Explanation of Format 


The I-O-CONTROL paragraph is optional. 

RERUN clause 

The RERUN clause causes rerun information to be recorded whenever integer-1 
RECORDS of file-name-2 have been processed. The ON DISK phrase is optional and is 
the default case. 


File-name-2 can be an input file or an output file, with any organization or access. 
File-name-2 cannot be specified in more than one RERUN clause. 
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SAME 


The two forms of the SAME clause (SAME AREA and SAME RECORD AREA) are used 
as follows: 


e More than one SAME clause can be included in a program; BOWevEr, the following 
rules apply: 


- A file-name must not appear in more than one SAME AREA clause. A file-name 
must not appear in more than one SAME RECORD AREA clause. 


~ Ifone or more file-names of aSAME AREA clause appear ina SAME RECORD 
AREA clause, all of the file-names in that SAME AREA clause must appear in 
the SAME RECORD AREA clause. However, additional file-names that do not 
appear in the SAME AREA clause can also appear in the SAME RECORD AREA 
clause. The rule that only one of the files mentioned ina SAME AREA clause 
can be open at any time takes precedence over the rule that all files mentioned 
ina SAME RECORD AREA clause can be open at any time. 


e The files referenced in the SAME AREA or SAME RECORD AREA clause need not 
all have the same organization or access. 


The SAME AREA clause specifies that two or more files that do not represent SORT 
or MERGE files are to use the:same memory area during processing. The area being 
shared includes all storage area assigned to the files specified; thus, only one file can be 
open at a time. 


The SAME RECORD AREA clause specifies that two or more files are to use the same 
memory area for processing of the current logical record. All the files can be open at the 
same time. A logical record in the SAME RECORD AREA is considered a logical record 
of each opened output file and the most recently read input file, which all have file-names 
appearing in this SAME RECORD AREA clause. This is equivalent to an implicit 
redefinition of the area; that is, records are aligned at the leftmost character position. 


MULTIPLE FILE 


The MULTIPLE FILE clause, which can be used only with sequential I/O, specifies the 
locations of files on a multiple-file reel. This clause is required when more than one file 
shares the same physical reel of tape. Regardless of the number of files on a single reel, 
only those files used in the object program need to be specified. 


The POSITION phrase is ignored by the compiler. You must specify the files in 
consecutive order. No more than one file on the same tape reel can be open at one time. 


One MULTIPLE FILE clause is used for each multiple-file tape. The titles of all the 
files listed in a given clause must have a common volume-identifier: otherwise, the 
files appear on different tapes. The volume-identifier is a nonnumeric literal, 1 to 17 
characters in length, that cannot contain any special characters or spaces. 


After each file is read or written to, the file is closed without being rewound (CLOSE 


file-name WITH NO REWIND) and the next file is opened without being rewound. If 
the volume-id is correct, the files are written to or read from the same reel. 
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See Also 


For more information about multiple-file tapes and device dependencies, refer to the J/O 
Subsystem Programming Guide. 


I/O Status 


The system can indicate to the COBOL74 program the status of I/O operations during 
their execution if the program specifies a FILE STATUS clause in the file-control entry. 
The FILE STATUS clause designates a two-character data item into which the system 
places a value that indicates the status of the I/O operation. For example, a value of 00 
means that the operation completed successfully. 


The type of file organization determines the I/O statements for which the system can 
give status values. 


The data item specified in the FILE STATUS clause is comprised of two numbers called 
status key 1 and status key 2. The leftmost character position of the FILE STATUS 
data item, called status key 1, indicates one of the following conditions on completion of 


the I/O operation: 
Status 
Value Meaning 
0 Successful Completion condition 
1 At End condition 
2 Invalid Key condition 
3 Permanent Error condition 
8 Condition defined by Unisys 
9 Condition defined by Unisys 


The rightmost character position of the FILE STATUS data item, called status key 2, 
further describes the results of the I/O operation. If no further information is available, 
status key 2 has a value of 0 (zero). On the following pages, this section provides tables 
of I/O status values and their meanings for each type of file organization. 


See Also 


For information about status values for the communication module, refer to Section 14, 
“COMMUNICATION SECTION.” 


Sequential I/O Status 


The execution of an OPEN, CLOSE, READ, SEEK, WRITE, or REWRITE statement 
causes the system to update the status of the I/O operation. The status value is updated 
before the program executes any applicable USE procedure. 
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Table 5—1 lists each status code value for sequential I/O operations and explains the 
meaning of the value reported. 


Table 5-1. Meaning of Status Code Values for Sequential I/O 


Value Meaning of Status Value 


00 The execution of the I/O statement was successful. 


A network warning or indication was returned by the system. You can get 
more information about the message by examining the values of the file 
attributes. 


An At End condition occurred during the execution of a sequential READ 
statement. The read operation was unsuccessful for one of the following 
reasons: 


e The program attempted to read a nonport file when no next cata 
record was present in the file. 


e The program executed a READ statement on an optional file that 
was unavailable when the associated OPEN statement was 
executed. 


The program attempted to read a port file when no next logical 
record was present and the communication path with the . 
correspondent endpoint was no longer established. (This is a Unisys 

extension.) 


An Invalid Key condition, (a Unisys extension for sequential 1/0) occurred 
for one of the following reasons: 


e The program executed a format 2 READ statement on a nonport file 
with the contents of the ACTUAL KEY data item less than 1 or 
greater than the ordinal number of the last record written to the file. 


e The program executed a format 2 WRITE statement for a record in a 
nonport file with the contents of the ACTUAL KEY data item less 
than 1 or greater than the last record allowed to be written because 

. of a maximum file size specification. 


e The program executed a format 2 READ or WRITE statement on a 
port file with the contents of the ACTUAL KEY data item less than 0 
or greater than the number of subfiles in the file (a boundary 
violation). . 


The execution of the I/O statement was unsuccessful because of an I/O 
error (Such as a data-check parity error, a transmission error, a security 
error, a control card error, a host service abort error, or a 

space-on-medium exhausted error). 


Permanent Error. This condition exists because of a boundary violation. 
This condition indicates that an attempt was made to write beyond the 
externally defined boundaries of a sequential file. 


File Not Open. The OFFER or AVAILABLE phrase was specified in an 
OPEN statement, and the file was not opened before control was 
returned to the next statement. 


continued 
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Table 5-1. Meaning of Status Code Values for Sequential I/O (cont.) 


Meaning of Status Value 


This value indicates a Form Not Found, a File Not Closed, or an 
Await-Open Failure condition. 


e Form Not Found. A READ FORM or WRITE FORM statement was 
performed on either a specific form that does not reside in the 
formlibrary or a form for which the compile-time version does not 
equal the run-time version. 


File Not Closed. An error occurred during the execution of the 
CLOSE statement and the file was not closed before contro! was 
returned to the next statement. 


Await-Open Failure. An error occurred during the execution of the 
AWAIT-OPEN statement. 


Short Block. Because of the limitation of the physical recording medium, 
the system is unable to determine whether or not the logical record 
returned was written to the file. Determination of the validity of the data 
record is the responsibility of the programmer. 


Data Error. When logical records are declared variable in length and the 
logical record length is supplied by the programmer (with the RECORD 
CONTAINS clause), a data error occurs on a READ, WRITE, or REWRITE 
statement if the logical record length supplied is less than the minimum 
record size or greater than the maximum record size declared for the file. 
This condition initiates no I/O operation and does not cause data to be 
transferred to or from the record area. 


Broadcast Write error. The WITH NO WAIT clause was used with the 
WRITE statement and an error occurred with the broadcast write 
operation. 


No data. The WITH NO WAIT clause was used with the READ 
statement, and no data was available. 


No buffer. The WITH NO WAIT clause was used with the WRITE 
statement, and no buffer was available. 


Timeout. A time limit elapsed before the transfer of data to or from the 
hardware device. 


Break on Output. For an output or I-O file, this condition occurs if the 
physical hardware device is equipped with a break so that the transfer of 
data in process can be halted. 


Unexpected /O error. An error may have occurred in the I/O operation, 
but its nature cannot be determined. . 
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Relative I/O Status 


The execution of an OPEN, CLOSE, READ, WRITE, REWRITE, DELETE, or START 
statement causes the system to update the status of the I/O operation. The status value 
is updated before the program executes any applicable USE procedure. 


Table 5-2 lists each status code value for relative I/O and explains its meaning. 


Table 5-2. Meaning of Status Code Values for Relative 1/0 


Value Meaning of Status Value 


The execution of the I/O statement was successful. 


An At End condition occurred during the execution of a Format 1 READ 
statement. The program tried to read a record when there was no next 
logical record in the file. 


An Invalid Key condition occurred and nee is no more information 
available. 


Duplicate key. An attempt was made to write a record to create a 
duplicate key in a relative file. oe 


No Record Found. An attempt was made to access a record identified by 
a key, but the record did not exist in the file. 


Boundary Violation. An attempt was made to write beyond the externally 
defined boundaries of a relative file. 


Permanent Error. The execution of the I/O statement was unsuccessful 
because of an I/O error (such as a data-check parity error, a transmission 
error, a security error, a control card error, a host service abort error, or a 
space-on-medium exhausted error). 


Short Block. Because of the limitation of the physical recording medium, 
the system cannot determine whether or not the logical record returned 
was written to the file. Determination of the validity of the data record is 
the responsibility of the programmer. 


Data Error. When logical records are declared variable in length and the 
logical record length.is supplied by the programmer (by the RECORD 
CONTAINS clause), a data error occurs on a READ, WRITE, or REWRITE 
statement if the logical record length supplied is less than the minimum 
record size or greater than the maximum record size declared for the file. 
This condition initiates no /O operation and does not cause data to be 
transferred to or from the record area. 


continued 
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Table 5-2. Meaning of Status Code Values for Relative I/O (cont.) 


Value Meaning of Status Value 


Timeout. A time limit elapsed before the transfer of data to or from the 
hardware device. 


Break on Output. For an output or I-O file, this condition occurs if the 
physical hardware device is equipped with a break so that the transfer of 
data in process can be halted. 


Unexpected I/O error. An error may have occurred in the I/O operation, 
but its nature cannot be determined. 


Indexed I/O Status 
The execution of an OPEN, CLOSE, READ, WRITE, REWRITE, DELETE, or START 
statement causes the system to update the status of the I/O operation. The status value 
is updated before the program executes any applicable USE procedure. 


Table 5-3 lists each status code value and explains its meaning. 
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Table 5-3. Meaning of Status Code Values for Indexed 1/0 


Value Meaning of Status Value 


The execution of the I/O statement was successful. 


An At End condition occurred during the execution of a Format 1 READ 
statement. The program tried to read a record when there was no next 
logical record in the file. 


An Invalid Key condition occurred and there is no more information 
available. 


Sequence error. The ascending sequence requirements of successive 
record key values have been violated, or the prime record key value has 
been changed between the successful execution of a READ statement 
and the execution of the next REWRITE statement for that file. 


Duplicate Key. An attempt was made to write a record to create a 
duplicate key in a relative file. 


No Record Found. An attempt was made to access a record identified by 
a key, but the record did not exist in the file. 


Boundary Violation. An attempt was made to write beyond the externally 
defined boundaries of a relative file. 


Permanent Error. The execution of the i/O statement was unsuccessful 
because of an I/O error (such as a data-check parity error, a transmission 
error, a security error, a control card error, a host service abort error, or a 
space-on-medium exhausted error). 


Short Block. Because of the limitations of the physical recording 
medium, the system cannot determine whether the logical record 
returned was written to the file. Determination of the validity of the data 
record is the responsibility of the programmer. 


Data Error. When logical records are declared variable in length and the 
logical record length is supplied by the programmer (by the RECORD 
CONTAINS clause), a data error occurs on a READ, WRITE, or REWRITE ~ 
statement if the logical record length supplied is less than the minimum 
record size or greater than the maximum record size declared for the file. 
This condition initiates no /O operation and does not cause data to be 
transferred to or from the record area. : 


Timeout. A time limit elapsed before the transfer of ai to or from the 
hardware device. 


Break On Output. For an output or I-O file, this condition occurs if the 
physical hardware device is equipped with a break so that the transfer of 
data in process can be halted. 


Unexpected I/O error. An error may have occurred in the I/O operation, 
but its nature cannot be determined. 
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ENVIRONMENT DIVISION Program Sample 


Example 5~1 shows coding of the ENVIRONMENT DIVISION. The program PAYROL 
includes both a CONFIGURATION SECTION and INPUT-OUTPUT SECTION in its 
ENVIRONMENT DIVISION. The SELECT clause in the FILE-CONTROL paragraph 
assigns two sequential files, INFIL and OUTFIL, to the storage medium TAPE. The 
SAME clause in the I-O-CONTROL paragraph (Format 1) specifies that INFIL and 
OUTFIL share the same memory area during processing. However, only one e these 
files can be open at a time. 


OG2806 IDENTIFICATION DIVISION. 

@G4806 PROGRAM-ID. PAYROL. 

826009 ENVIRONMENT DIVISION. 

@2809G CONFIGURATION SECTION. 

819606 SOURCE-COMPUTER. Al7. 

12088 OBJECT-COMPUTER. A17. 

814060 SPECIAL-NAMES. 

816200 SW5 ON STATUS IS SW5-ON 
618826 OFF STATUS IS SW5-OFF; 
B2B008 CURRENCY SIGN IS "E"; 

B22880 DECIMAL-POINT IS COMMA. 
@24960 INPUT-OUTPUT SECTION. 

826006 FILE-CONTROL. — 

828898 SELECT INFIL ASSIGN TO TAPE. 
038908 SELECT OUTFIL ASSIGN TO TAPE. 
832000 I-0-CONTROL. 

934890 SAME AREA FOR INFIL OUTFIL. 


Example 5-1. Coding the ENVIRONMENT DIVISION 
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Section 6 
Data Concepts 


To understand the DATA DIVISION, you need to understand some of the concepts that 
pertain to the data in your program. The record concept encompasses structure, record 
level, and data items within the record. The data concept includes categorizing of data, 
aligning data, and referring to data. The table concept for handling sets of data includes 
subscripting and indexing. The edit concept for formatting data includes using symbols 
to format data, insertion editing, and zero-suppression and replacement editing. 


Records 


The most inclusive data item is the logical record. The record is identified by a 01-level 
entry. One or more related data items are defined in the record. 


A data-description entry is an entry in the DATA DIVISION that describes a data item. 
Each data-description entry consists of a level-number followed by a data-name, if 
required, followed by a series of independent clauses, as required. 


Arecord description is a set of data-description entries that describe the characteristics 
of the particular record. You can specify the following in a record description: 


e The items that are included in the record 

e The order in which the items appear in the record 

e The way the items are related to each other in the record 

The size of a record description is the sum of the maximum sizes of all items subordinate 


to a 01-level item. The maximum size of a record description is restricted by the explicit 
or implicit usage of the 01-level item as shown in Table 6-1. 


Table 6-1. Usage and Maximum Size of a Record Description 


Usage Maximum Size 


BINARY or DISPLAY 65,535 characters 


COMP | 65,535 digits 
- TASK, EVENT, INDEX, or LOCK 65,535 words 
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Levels 


Logical records have subdivisions for data reference. The items in these subdivisions 
are organized with a system of levels. Once a subdivision has been specified, it can be 
further subdivided to permit more detailed data referral. 


Understanding Elementary and Group Items 


6-2 


The smallest element of a data description is called an elementary item. Notice that 
elementary items cannot have subordinate levels. A record consists of a sequence of 
elementary items or of one elementary item. 


To refer to elementary items as a set, you can combine the elementary items into groups. 
Each group consists of a named sequence elementary items of one or more elementary 
items. You can combine groups, in turn, into groups of two or more groups. Thus, an 
elementary item can belong to more than one group. of one or more elementary items. 
You can combine groups, in turn, only of a level-number and a data-name, optionally 
followed by a VALUE, USAGE, or REDEFINES clause, followed by a period. 


A group includes all group and elementary items following it until a level-number occurs 
that is less than or equal to the level-number of that group. You must describe all items 
immediately subordinate to a given group item by using identical level-numbers greater 
than the level-number used to describe that group item. 


COBOL74 defines all group items to be alphanumeric. The compiler aligns each group 
item on a byte boundary. The “FILLER ADDED” message appears where such 
alignment has taken place. 


Note: No elementary dataitem can start more than 65,535 bytes (131,070 
COMPUTATIONAL digits) from the beginning of the 01-level record 
in which the data item is contained. In addition, no elementary data 
item whose USAGE IS COMPUTATIONAL can start more than 
32,767 bytes (more precisely, 65,535 COMPUTATIONAL digits) 
from the beginning of the 01-level record in which the data item is 
contained. 


Example 


Example 6-1 shows the coding of elementary and group items. A group is composed 
of all group and elementary items described under it. A group item ends when 

a level-number less than or equal to the numeric value of the group item itself is 
encountered. 
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B28G00* 

Q3G880* The name of the record is PRODUCTION-RECORD. 
G320800* 

934908 @1 PRODUCTION-RECORD. 

B36G00* 

@38G00* ITEM-NO and LOT-NO are elementary items. 
B4ABGBO* 

B42680 93 ITEM-NO PIC 9(5). 

B44GOG © 93 LOT-NO PIC 9(6). 

B46G02* 


G48000* The first group item is ITEM-DATE. The elementary items MONTH, 
@48980* DAYS, and YEAR are subordinate to ITEM-DATE. STANDARD-COST 
@48950* is an elementary item. 


959808* 

952020 93 ITEM-DATE. 

B68008 @5 MONTH PIC 99. 
862000 85 DAYS PIC 99. 
864080 85 YEAR PIC 99, 
072088 63 STANDARD-COST PIC 9(5)V99. 
866020* 


G68820* Both PRODUCTION-CODE and MACHINE-SHOP are group items. — 
G68982* The items MILLING and FINISHING are elementary items 

G68919* subordinate to the MACHINE-SHOP group item. The items 
@68929* ASSEMBLY, INSPECTION, and WARRANTY-CODE are elementary items. 
%68938* The group item PRODUCTION-CODE ends with the INSPECTION data 
268948* item. 


87 B080* . 

974808 83 PRODUCTION-CODE. 

876888 @5 MACHINE-SHOP. | 

B84060 87 MILLING PIC 999. 
986008 87 FINISHING PIC 99. 
B88000 85 ASSEMBLY PIC 9(4). 
G9BBOB @5 INSPECTION ~ PIC X(5). 


G92808 @3 WARRANTY-CODE PIC XX. 
| Example 6-1. Coding Elementary and Group Items 


Organizing Data with Level-Numbers 


A system of level-numbers shows the organization of elementary items and group items. 
Because records are the most inclusive data items, level-numbers of records start at 

01. You should assign less inclusive data items higher (but not necessarily successive) 
level-numbers that are not greater in value than 49. The program writes separate 
entries for each level-number used. 


The special level-numbers 66, 77, and 88 represent entries for which no true concept of 
level exists. 
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Constructing a Record 


Table 6-2 shows the type of entry that can be assigned to each type of level-number. — 


Table 6-2. Assigning Level-Numbers 


Level-Number . Related Entry 


01 The first entry in each record description. Multiple 01-level 
entries subordinate to a level indicator other than RD 
represent implicit redefinitions of the same area. 


02 through 49 The hierarchy of data in a logical record. 
66 RENAMES clause entries for regrouping data items. 


77 WORKING-STORAGE or LINKAGE:SECTION items that are 
not organized into a hierarchy. 


88 Condition-names that specify values of conditional variables. 


A level-number is required as the first element in each data-description entry. Table 6-3 
shows the level-numbers that can be used with each type of data-description entry: 

file description (FD), sort merge description (SD), communications description (CD), 
report description (RD) and the data-description entries in WORKING STORAGE and 
LINKAGE SECTIONs. a 


Table 6-3. Level-Numbers Associated with Data-Description Entries 


Data-Description Entry ‘Level-Numbers Allowed . 


FD, SD, or CD Level-numbers 01 through 49, 66, or 88 


RD — Level-numbers 01 through 49 


Data-description entries in Level-numbers 01 through 49, 66, 77, or 88 
WORKING-STORAGE and LINKAGE 
SECTIONs 


Example 


Example 6-2 illustrates a record description in COBOL74 for a record called 
EMPLOYEE-INFO. The PICTURE clause is associated with each elementary item. 


In the example, the following information applies: 


-@ The EMP-PAY-DATA group includes all items until the EMP-LAST-REVIEW group, 
which has an equal level-number. _ 


e The EMP-DEDUCTIONS group includes all items until the EMP-LAST-REVIEW 
group, which has a lower level-number than EMP-DEDUCTIONS. 
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e The EMP-DEDUCTIONS group is a part of the EMP-PAY-DATA group. 
e The EMP-INSURANCE group is a part of the EMP-DEDUCTIONS group. 
e EMP-HOSPITAL is a part of the EMP-INSURANCE group. 


91 EMPLOYEE-INFO. 


93 EMP-NO PIC 9(5). 
83 EMP-COST-CNTR PIC 99. 
93 EMP-NAME. 
@5 EMP-LAST-NAME PIC X(13). 
85 EMP-FIRST-INITIAL PIC X. 
85 EMP-M-INITIAL PIC X. 
93 EMP-ANNUAL~SALARY PIC 9(6)V99. 
83 EMP-DT-HIRED. 
@5 EMP-H-MONTH PIC 99. 
@5 EMP-H-DAY _ PIC 99. 
05 EMP-H-YEAR PIC 99. 
83 EMP-PAY-DATA. 
@5 EMP--GROSS PIC 9(6)V99. 
85 EMP-DEDUCTIONS. 
@7 — EMP-INSURANCE. 
@9 EMP-HOSPITAL PIC 9(4)V99. 
@9 EMP-LIFE PIC 9(4)V99. 
7  EMP-TAXES. 
@9 EMP-FICA - PIC 9(4)Vv99. 
69 EMP-STATE-TAX PIC 9(4)Vv99. 
@9 EMP-WITHHOLDING PIC 9(4)V99. 
Q3 EMP-LAST-REVIEW. 
@5 EMP-R-MONTH PIC 99. 
@5 EMP-R-DAY PIC 99. 


Example 6-2. Level-Number Construction for a Record 


Data 


Data handling in COBOL includes classifying data into categories and classes, qualifying 
data to ensure uniqueness, and positioning data in a receiving field. 

Classifying Data into Categories and Classes 
COBOL74 supports the following seven categories of data items: 


e Alphabetic 
e Numeric 


e Numeric-edited 
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e Alphanumeric 

e Alphanumeric-edited 

e Kanji 

e Kanji-edited 

These seven categories of data items are grouped into the following three classes: 


e Alphabetic 

e Numeric 

e Alphanumeric 

For alphabetic and numeric data items, the classes and categories are synonymous. The 
alphanumeric class includes the categories of alphanumeric-edited, numeric-edited, 
alphanumeric (without editing), Kanji, and Kanji-edited. Every elementary item, except 
an index data item, belongs to one of the classes and also to one of the categories. The 


class of a group item is treated at execution time as alphanumeric regardless of the class 
of the elementary items subordinate to that group item. 


Table 6-4 depicts the relationship of the classes and categories of data items. 


Table 6—4. Classes and Categories of Data Items 


Level of Item | Category 


Elementary Alphabetic Alphabetic - 
Numeric Numeric 
Alphanumeric Numeric-edited 
- Alphanumeric 
Alphanumeric-edited 
Kanji 


Kanji-edited 


Alphanumeric Alphabetic 
Numeric 
Numeric-edited 
Alphanumeric 
Alphanumeric-edited 
Kanji 


Kanji-edited 
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Qualifying Data to Ensure Uniqueness 


Every user-specified identifier that defines an element in a COBOL source program must 
be unique. The user-specified identifier can be unique if it meets one of the following 
two conditions: 


e No other name has the identical spelling and hyphenation. 


e The name exists within a hierarchy of names. You can make a name unique by 
mentioning one or more of the higher levels of the hierarchy when you refer to the 
name. 


The higher-level names in the hierarchy are called qualifiers. The process that ensures 
uniqueness is called qualification. You must provide enough qualification to make the 
name unique. Unless it is necessary to make the name unique, you do not need to 
specify all the levels of the hierarchy. 


In the DATA DIVISION, you must associate all data-names used for qualification with 
a level indicator or a level-number. Therefore, two identical data-names must not 
appear as entries subordinate to a group item unless they can be made unique through 
qualification. 


In the hierarchy of qualification, names associated with a level indicator, such as a file 
description (FD), are the most significant. The next most significant names are those 
associated with level-number 01, then level-number 02, and so on through 49. 

The most significant name in the hierarchy must be unique and cannot be qualified. . 
You can make subscripted or indexed data-names, conditional variables, 
procedure-names, and data-names unique by qualification. Regardless of the available 
qualification, no name can be both a data-name and a procedure-name. 

You can qualify a data-name, a condition-name, a paragraph-name, or a text-name by 
specifying one or more phrases composed of an IN or an OF keyword followed by a 
qualifier. The keywords IN and OF are logically equivalent. 


Bach qualifier must be of a successively higher level and must be within the same 
hierarchy as the name it qualifies. 


The same name must not appear at two levels in a hierarchy. 


Qualification has three formats. These formats are used as follows: 


Format Explanation 
1 Qualifies a data-name or a condition-name. 
2 Qualifies a paragraph-name. 
3 Qualifies a COPY library-name. 
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Format 1 


The Format 1 qualification is as follows: 


enna } a les 
ne data-name-2 
condition-name IN 


Explanation of Format 1 
The rules for qualifying a data-name or condition-name are as follows: 


e You can use the name of a conditional variable as a qualifier for any of the 
. condition-names of the variable. 


e Ifadata-name or a condition-name is assigned to more than one data item ina 
source program, you must qualify the data-name or a condition-name each time it is 
referenced in the PROCEDURE, ENVIRONMENT, and DATA DIVISIONSs (except 
in the REDEFINES clause where qualification is unnecessary and must not be used). 


e A data-name cannot be subscripted when it is being used as a qualifier. 


e Aname can be qualified even if it does not require qualification. If more than one 
combination of qualifiers ensures uniqueness, any partial set of qualifiers for another 
set of qualifiers for a data-name must not be the same as any partial set of qualifiers 
for another data-name. Qualified data-names can have up to 49 qualifiers, inclusive. 


The following example illustrates qualified names: 


@1 EMP-FULL-NAME 
83 LAST-NAME 
@3 FIRST-NAME 
@3 MIDDLE-NAME 
@1 EMP-NAME 
@3 LAST-NAME 
@3 FIRST-NAME 
@3 MIDDLE-INITIAL 


In this example, because LAST-NAME is not unique, it must be used with a 
qualifier to specify either LAST-NAME OF EMP-FULL-NAME or LAST-NAME 
OF EMP-NAME. Because MIDDLE-INITIAL is unique, it can be used without 
qualification. However, qualifying MIDDLE-INITIAL as MIDDLE-INITIAL OF 
EMP-NAMSE is also correct. 
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Format 2 


The Format 2 qualification is as follows: 


ns} oston am 
paragraph-name IN section-name 


Explanation of Format 2 
A section-name is the highest and only qualifier available for a paragraph-name. 
You must not duplicate a paragraph-name in a section. When you qualify a 


paragraph-name with a section-name, do not include the word SECTION. You do not 
have to qualify a paragraph-name if you refer to it within the same section. 


Format 3 


The Format 3 qualification is as follows: 


text-name Neat ibrary-name| 


Explanation of Format 3 

If text-name is unique, it defaults to the library it is in. Otherwise, you must qualify the 

text-name each time you refer to it. You must also qualify the text-name if more than 

one COBOL library is available to the compiler during compilation. 
Aligning Data 

‘The positioning of data within an elementary item by using a move operation depends 


on the data category of the receiving item. Table 6-5 describes the alignment rules that 
apply for each category of data item. 
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'| Data Category Alignment Rules 


Table 6-5. Alignment Rules for Move Operation by Data Categories 


Numeric. Aligns the data by decimal point and moves it to the 
. receiving character positions with zero-fill or truncation on 
either end, as required. If you do not specify an assumed 
decimal point, the compiler treats the data item as if it had 
an assumed decimal point immediately following its 
rightmost character and aligns it as previously described. 


Numeric-edited Aligns the data that was moved to the edited data item; the 
data is aligned by decimal point with zero-fill or truncation at 
either end, as required, within the receiving character 
positions of the data item, except where editing requirements 
cause replacement of the leading zeros. 


Alphanumeric (other than a Moves the sending data to the receiving character positions 
numeric-edited data item), and aligns it at the leftmost character position in the data 
alphanumeric-edited, or item with space-fill or truncation to the right, as required. 
alphabetic 

Kanji or Kanji-edited Moves the sending data to the receiving character positions 


and aligns it at the leftmost character position in the data 
item. Fills the receiving data item on the right with Kanji 
space characters or truncates it from the right to fully occupy 
the field. 


See Also 


For information on aligning data in the receiving field of an alphanumeric move 
operation, refer to “JUSTIFIED Clause” in Section 7, “DATA DIVISION.” 


Tables 


6-10 


A table is a set of logically consecutive data items that you specify in the DATA 
DIVISION with an OCCURS clause. By using a table, you can do the following with your 


data: | 


e Define contiguous data items. 

e Access an item by its position in the table. 

e Specify the number of repetitions for an item. 

e Identify each item with a subscript or an index. 

e Access items in multidimensional, variable-length tables. 
e Specify ascending or descending keys. 


e Search a dimension of a table for an item that satisfies a specified condition. 
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You can define a table composed of contiguous data items by including the OCCURS 
clause in a data-description entry. The OCCURS clause specifies that the item is to be 
repeated the number of times you designate. 


The item is considered a table element, and the name and description of the item apply 
to each repetition or occurrence. Because each table element does not have a unique 
data-name, you must refer to a desired occurrence by specifying the table element 
data-name and the desired occurrence number. You can specify an occurrence number 
with subscripting or indexing. 


See Also 


For information about how to define the number of items in a table, refer to “OCCURS 
Clause” in Section 7, “DATA DIVISION.” 


Defining Tables 


To define a one-dimensional table, you must use an OCCURS clause as part of the 
data description of the table element. The OCCURS clause must not appear in the 
description of group items that contain the table element. 


Example 6-3 shows a one-dimensional table definition. 


81 TABLE-1. 
@3 TABLE-ELEMENT OCCURS 28 TIMES 
@5 NAME PIC X(38) 
@5 SSAN PIC 3(6). 


Example 6-3. Defining a One-Dimensional Table 


To create a two-dimensional table, you need to define a one-dimensional table within 
each occurrence of an element of another one-dimensional table. To accomplish this, 
include an OCCURS clause in the data description of the element of the table and in 
the description of only one group item that contains that table element. To define a . 
three-dimensional table, you must include the OCCURS clause in the data description of 
the element of the table and in the description of two group items that contain that table 
element. In COBOL, you can define tables of up to 48 dimensions. 


Example 
Example 6-4 is a table with the following dimensions: 
e One dimension for CONTINENT-NAME. The CONTINENT-NAME occurs eight 


times within the table. 


e Two dimensions for COUNTRY-NAME. The COUNTRY-NAME occurs 15 times 
within each CONTINENT- NAME. 


e Three dimensions for CITY-NAME and CITY-POPULATION. The CITY-NAME and 
the CITY-POPULATION occur 20 times within each COUNTRY-NAME. 
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The table includes 4,928 data items grouped as follows: 


Number of Data Items Dimension 

8 CONTINENT-NAME 
120 COUNTRY-NAME 
2,400 CITY-NAME 

2,400 CITY-POPULATION 


Example 6—4 shows the data-description entries for a three-dimensional table definition. 


@1 CENSUS-TABLE. 


@5 CONTINENT-TABLE OCCURS 8 TIMES. 
18 CONTINENT-NAME PIC X(16). 
1@ COUNTRY-TABLE OCCURS 15 TIMES. 
15 COUNTRY-NAME © PIC X(18). 
15 CITY-TABLE ~ OCCURS 28 TIMES. 
26 CITY-NAME PIC X(19) 


28 CITY-POPULATION PIC X (12) 
Example 6-4. Defining a Three-Dimensional Table 


In this example, CITY-NAME(3,7,19) refers to the nineteenth city of the seventh 
country of the third continent. 


Accessing Tables 


Whenever a program refers to a table element, the reference must indicate the intended 
occurrence of the element. For access to a one-dimensional table, the occurrence 
number of the desired element provides complete information. For access to tables of 
more than one dimension, an occurrence number must be supplied for each dimension of 
the table accessed. | 


In Example 6-4, shown earlier in this section, a reference to the fourth CONTINENT- 
NAME is complete, but a reference to the fourth COUNTRY-NAME is not. To refer to 
the dimension COUNTRY-NAMBE, which is an element of a two-dimensional table, the 


fourth COUNTRY-NAME within a particular CONTINENT-NAME must be referenced. 


Subscripting 


6~12 


A subscript is an integer or a data-name whose value refers to an individual element in a 
list or table of like elements that have not been assigned individual data-names. 


To use a subscript, you must first provide an OCCURS clause to define multiple 


occurrences of a data item. The data items to be repeated must all have the same 
format. 
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The format for subscripting follows: 


{ data-name 
condition-name 


} (subscript-1 [, subscript-2 [, subscript-3 ] ...] ) 


Explanation of Format 
The subscript identifies the table element that is to be accessed. 


After the table element data-name, you must delimit the subscript or the set of 
subscripts that identifies the table element by enclosing the subscripts in parentheses. 
The table element data-name with its appended subscript is called a subscripted 
data-name or an identifier. . 


When more than one subscript is required, write the subscripts in descending order of 
inclusive dimensions of the data organization. . 


You can use a subscript ina PERFORM statement. If you use the VARYING option, 
the compiler initializes, increments, and tests the subscript during execution of the 
procedure. If you use the UNTIL or TIMES option, you must provide additional code to 
initialize and increment the subscript. 


- You can represent the subscript either by a numeric literal that is an integer or by 
a data-name that is a numeric elementary item representing an integer. When you 
represent the subscript with a data-name, you can qualify the data-name but not 
subscript it. | 


In the REPORT SECTION of Report Writer, you cannot use a sum counter or the special 
registers LINE-COUNTER and PAGE-COUNTER as subscripts. 


The subscript can be signed; if signed, it must be positive. The lowest possible subscript 
value is 1, which points to the first element of the table. Subscripts whose values are 

2, 3, and so on point to subsequent sequential elements of the table. The highest 
permissible subscript value is the maximum number of occurrences of the item, as 
specified in the OCCURS clause. | 


When a program executes a statement that refers to subscripted table elements, the 
compiler tests each subscript specified (except a numeric literal) to ensure that its value 
is not less than 1 or greater than the maximum number of occurrences specified by the 
corresponding OCCURS clause (as modified by the DEPENDING ON clause, if one 
exists.) If the subscript value is not in this range, the program ends abnormally. 


At compilation time, if a subscript is a numeric literal and its value is not in the range, 


the compiler issues the proper warning. An invalid index occurs at run time if the 
program attempts to access an item beyond the end of the 01-level record. 
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See Also 


For information on defining the number of items in a table, refer to “OCCURS Clause” 
in Section 7, “DATA DIVISION.” | 


Indexing 


An index, like a subscript, also identifies the individual elements in a table of like 
elements. The compiler assigns an index to the level of the table when the program 
defines the table with an INDEXED BY phrase in the OCCURS clause. The name 

given in the INDEXED BY phrase is called an index-name and refers to the assigned 
index. The value of an index corresponds to the occurrence number of an element in the 
associated table. 


To assign a value to an index-name, the program must execute a SET statement, a 
SEARCH ALL statement, or a Format 4 PERFORM statement. 


The general format for indexing follows: 


data-name index-name-1 +). 
literal-2 
ee { ed a } = 


, | {* \ literal-4 


[ findexname 3} 11} ieerat6] |..| 


Explanation of Format 


An index-name has the same internal representation as an index data item. Ifa value 
to be stored in an index-name or an index data-name exceeds the largest value that can 
be held in that index-name or index data-name, the value is truncated. The truncation 
is executed according to the rules for size error conditions in an arithmetic statement 
without a SIZE ERROR phrase. (This is a Unisys extension.) 


An index-name assigned to one table cannot be used to index another table. (This is a 
Unisys extension.) 


You can specify direct indexing by using an index-name in the form of a subscript. You 
ean specify relative indexing by following the index-name with the operator plus sign 
(+) or minus sign (—), followed by an unsigned integer numeric literal, all of which 

are delimited by parentheses following the table element data-name. The compiler 

determines the occurrence number resulting from relative indexing by incrementing - 

(when the operator + is used) or decrementing (when the operator — is used) the 

occurrence number by the value of the literal. The occurrence number is represented 
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by the value of the index. When more than one index-name is required, the names are 
written in descending order of inclusive dimensions of the data organization. 


When the program executes a statement that refers to an indexed table element, the 
value of each direct or relative index should not be as follows: 


e Less than a value that corresponds to the beginning of the first occurrence of the 
table element 


e Greater than a value that corresponds to the beginning of the last occurrence of the 
table element (as determined by the OCCURS clause) 


The index value need not precisely address the beginning of a table element to pass 

the range check. For example, you can set an index-name to the value of an index data 

item that has been set to the value of another index-name (such assignments are made 

without conversion). A program ends if an attempt is made to access beyond the end of 
the 01-level record. 


An indexed table reference can contain either an index or a subscript. (This is a Unisys 
extension.) Object code is generated to verify the validity of subscripts on each table 
reference (unless the OPTIMIZE compiler control option is set.) 


In contrast, the contents of an index-name are not verified by the generated object code, 
either during the execution of the SET statement that modifies the index-name or 
during references to the table. 


Thus, you must ensure that the contents of an index-name are valid for the table that 

it refers to at execution time. This applies to subscripts as well. Failing to observe 
the table limits can produce unexpected results in those cases where the values of the 
index-name are incorrect but do not cause access outside the bounds of the 01-level 
record. These same values can terminate a program abnormally. 


Unisys strongly discourages the use of inappropriate index values to access parts of an 
01-level record outside the bounds of the table. 


See Also 


e For information about specifying indexes, refer to “OCCURS Clause” in Section 7, 
“DATA DIVISION.” 


e For information about specifying the format of a data item in storage, refer to 
“USAGE Clause” in Section 7, “DATA DIVISION.” 


Editing 


Editing is the process of using symbols in the PICTURE clause to specify the format of 
data for output reports. The editing operation occurs as the data item is moved from the 
sending field to the receiving field. 
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‘Some of the applications for which you might want to use editing include the following: 


e Separating fields with delimiters such as zeros or spaces 

e Adding asterisks for protection of amounts on checks 

e Adding credit or debit symbols for accounting purposes 

e Formatting monetary values with commas (,) and dollar signs (§) 

e Indicating positive or negative values with plus (+) and minus (-) signs 


e Preceding the fractional part of an amount with a decimal point (.) 


Describing Elementary Items with Symbols 


6-16 


Elementary items are described in the PICTURE clause with the symbols shown in 
Table 6-6. 


Table 6-6. Describing Elementary Items Using Symbols 


| Symbol Explanation 


Each A in the character string represents a character position that can contain 
only a letter of the alphabet or a space. 


Each B in the character string represents a character position into which the 
space character is inserted. 


Each P indicates an assumed decimal scaling position and specifies the location 
of an assumed decimal point when the point is not within the number that 
appears in the data item. The scaling position character P is not counted in the 
size of the data item, but scaling position characters are counted in determining 
the maximum number of 23 digit positions in numeric-edited items or numeric 
items. 


The scaling position character P can appear only to the left or right as a 
continuous string of Ps in a PICTURE description. Because the scaling position 
character P implies an assumed decimal point to the left of the P characters if 

these characters are the leftmost PICTURE characters, and to the right if the P 
characters are the rightmost PICTURE characters, the assumed decimal point 

symbol V is redundant as either the leftmost or the rightmost character in such 
a PICTURE description. The character P and the insertion character period (.) 

cannot both occur in the same PICTURE character string. | 


If, in any operation involving conversion of data from one form of internal 
representation to another, the data item being converted is described with the 
PICTURE character P, each digit position described by a P is considered to 
contain the value O and the size of the data item is considered to include the 
digit positions so described. 


continued 
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Table 6-6. Describing Elementary Items Using Symbols (cont.) 


Symbol Explanation 


The letter S in a character string indicates the presence of an operational sign in 
the internal representation of a numeric data item. The S must be the first 
(leftmost) character in the character string. . 


The symbol S can be used in the PICTURE character string of any data item 
with the USAGE clause equal to DISPLAY, COMPUTATIONAL, or BINARY. The — 
SIGN clause can be uSed to specify the exact representation and position of the 
operational sign. 


When an operational sign is specified for a DISPLAY data item and a SIGN 
clause is not specified, the sign is maintained and expected in the zone of the 
least significant (rightmost) character. When the data item is in the receiving 
field in an arithmetic statement and when the native character set is EBCDIC, 
the four zone bits are set to binary 1101 for negative values and to binary 1100 
or 1111 for positive values. 


When the data item is used in an algebraic comparison or operation to supply 
an algebraic value, specification of the least significant zone as binary 1101 
causes the value to be considered negative. . 


Only the zone values 1100, 1101, and 1111 qualify the data item as 
NUMERIC if it is tested by the numeric class condition. For DISPLAY data 
items, the presence or absence of an operational sign has no effect on the 
amount of storage required to contain the data item, unless the SIGN 
SEPARATE clause is specified. 


When an operational sign is specified for a COMPUTATIONAL data item and a 
SIGN clause is not specified, the sign is maintained and expected as a leading, 
separate 4-bit character to the left of the most significant digit position. 


When the native character set is EBCDIC, the binary pattern of the sign 
character is 1101 for negative values and 1100 for positive values. Like 
DISPLAY data items, only these values allow the item to be considered 
NUMERIC in the class condition test. Unlike DISPLAY data items, the 
specification of an operational sign for COMPUTATIONAL data items increases 
by one the number of 4-bit character positions occupied by the data item in 
storage. 


The letter V in a character string indicates the location of the assumed decimal 
point and can appear only once in a character string. The symbol V does not — 
represent a character position and, therefore, is not counted in the size of the 
elementary item. When the assumed decimal point is to the right of the 
rightmost character in the string, the V is redundant. 


X Each letter X in the character string represents a character position that 
contains any allowable character from the character set. 


continued 
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Table 6-6. Describing Elementary Items Using Symbols (cont.) 


Symbol Explanation 


Each letter Z in a character string can represent only the leftmost leading 
numeric character positions that are replaced by space characters when the 
contents of the character positions are 0. Each symbol Z is counted in the size 
of the item. 


9 Each numeral 9 in the character string represents a character position that 
contains a numeral and is counted in the size of the item. 


0 Each numeral zero (0) in the character string represents a character position in 
which the numeral 0 is inserted. The numeral 0 is counted in the size of the 
item. ; 


/ (slash) Each slash (/) in the character string represents a character position into which 
the slash character is inserted. The slash is counted in the size of the item. 


, (comma) Each comma (/) in the character string represents a character position into 
which the comma character is inserted. This character position is counted in 
the size of the item. The comma must not be the last character in the PICTURE 
character string. 


. (period) When the period (.) appears in the character string, it represents the decimal 
point for alignment purposes and also represents a character position into 
which the period character is inserted. The period is counted in the size of the 


item. 


For a given program, the functions of the period and comma are exchanged if 
the clause DECIMAL-POINT IS COMMA is stated in the SPECIAL-NAMES 
paragraph. In such an exchange, the rules for the period apply to the comma, 
and the rules for the comma apply to the period wherever these characters 
appear in a PICTURE clause. 


A period immediately followed by a nonblank character is considered to be an 
insertion character, even if the nonblank character is not part of the PICTURE 
character string. For a period in the last character position of the PICTURE 
character string to be treated as an insertion character, it must be immediately 
followed by another period. The second period ends the data-description entry. 
Thus, a PICTURE clause must be the last clause in the data-description entry if 
it has a period as an insertion character in the last character position of the 
PICTURE character string. ° 


These symbols are editing sign-control symbols. When used, these symbols 
represent the character position into which the editing sign-control symbol is 
placed. The symbols are mutually exclusive in any character string, and each 
character used in the symbol is counted in determining the size of the data 

item. 


continued 
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Table 6-6. Describing Elementary Items Using Symbols (cont.) 


Symbol Explanation 


* (asterisk) Each asterisk (*) in the character string represents a leading numeric character 
position into which an asterisk is placed when the content of that position is O 
(zero). Each asterisk is counted in the size of the item. Try to avoid the use of 
an asterisk in a PICTURE character string for purposes other than as a 
leading-zero-replacement mechanism. Although this use of an asterisk may 
produce expected results under certain circumstances, it is not a supported 
feature. 


$ (dollar The dollar sign ($) in the character string represents a character position into 

sign) which a currency symbol is to be placed. The currency symbol in a character 
string is represented by either the dollar sign or the single character specified in 
the CURRENCY SIGN clause in the SPECIAL-NAMES paragraph. The currency 
symbol is counted in the size of the item. 


Insertion Editing 
You can use the following four types of insertion editing: 
e Simple insertion editing 
e Special insertion editing 
e Fixed insertion editing 
e Floating insertion editing 


You can also use another method, zero-suppression and replacement SEDEs which is 
described later in this section. 


Simple Insertion Editing 


Simple insertion editing uses the space character (B), slash (/), and comma (,) as 
insertion characters. Also, simple insertion editing uses any characters that are not 
defined symbols as insertion characters. These characters include the right parenthesis, 
left parenthesis, and any digits (other than 9) that are not used in the strict syntax to 
indicate consecutive occurrences of a preceding symbol. Precedence rules for these 
characters and rules for determining data categories are the same as those for the simple 
insertion character 0 (zero). (This is a Unisys extension.) | 


You might want to use simple insertion editing for formatting telephone numbers, dates, 
Social Security numbers, and so on. 


The insertion characters are counted in the size of the item and represent the position 


in the item into which the character is inserted. Table 6-7 shows examples of valid 
PICTURE clauses using simple insertion editing. 


8600 0296-000 7 6-19 


Data Concepts 


Table 6-7. Simple Insertion Editing Examples 


Picture Actual Representation 


Special Insertion Editing 


Special insertion editing uses the period (.) as the insertion character. Besides being an 
insertion character, the period represents the decimal point for alignment purposes. The 
insertion character used for the actual decimal point is counted in the size of the item. 
You cannot use both the assumed decimal point symbol (V) and the actual decimal point 
symbol (.) in the same PICTURE character string. Special insertion editing results in 
the insertion character appearing in the item in the same position as is shown in the 
character string. 


Table 6-8 illustrates the use of special insertion editing. 


Table 6-8. Special Insertion Editing Example 


Picture Actual Representation 


Fixed Insertion Editing 
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Fixed insertion editing uses the dollar sign ($) and the editing sign-control symbols, the 
plus sign (+), the minus sign (-), the credit symbol (CR), and the debit symbol (DB) as 
the insertion characters. Only one dollar sign and only one of the editing sign-control 
symbols can be used in any PICTURE character string. 


When the symbol CR or DB is used, it represents two character positions in determining 
the size of the item, and it the symbol must represent the rightmost character position 
that is counted in the size of the item. The plus and minus sign symbols, when used, 
must be in either the leftmost or the rightmost character position to be counted in the 
size of the item. The dollar sign must be the leftmost character position to be counted in 
the size of the item, except that it can be preceded by either a plus or minus sign. 


Fixed insertion editing results in the insertion character occupying the same character 
position in the edited item as it occupied in the PICTURE character string. The results 
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produced by editing sign-control symbols depend on the value of the data item, as shown 
in Table 6-9. For example, if the edit symbol is the minus sign and the data item is 
negative, the data item has a minus sign. However, if the edit symbol is the minus sign 
and the data item is positive or 0 (zero), the data item has a space. 


Table 6-9. Data Item Values and Results of Editing Sign Control Symbols 


Editing Symbol in Results If Data Item Is Results If Data Item Is 
PICTURE Character String Positive or Zero Negative 


+ 
Space 
2 spaces 


2 spaces 


Floating Insertion Editing 


Floating insertion editing uses the dollar sign ($) and the two editing sign-control 
symbols, the plus sign (+) and the minus sign (—) as insertion characters. These 
insertion characters are mutually exclusive in the same PICTURE character string. 


Floating insertion editing is indicated in a PICTURE character string by using a string of 
at least two of the same floating insertion characters. This string of floating insertion 
characters can contain any of the fixed insertion symbols or have fixed insertion 
characters immediately to the right of the string. These insertion characters are part of 
the floating string. 


The leftmost character of the floating insertion string represents the leftmost symbol in 
the data item. The rightmost character of the floating string represents the rightmost 
limit of the floating symbols in the data item. 


The second floating character from the left represents the leftmost limit of the numeric 
data that can be stored in the data item. Nonzero numeric data can replace all 
characters at, or to the right of, this limit. 


In a PICTURE character string, floating insertion editing can be represented in two 
ways: 


e Any or all of the leading numeric character positions to the left of the decimal point 
can be represented by insertion characters. 


e All numeric character positions in the PICTURE character string can be represented 
by insertion characters. — 


If the insertion characters are present only to the left of the decimal point in the 
PICTURE character string, a single floating insertion character is placed in the character 
position immediately preceding either the decimal point or the first nonzero digit in the 
data represented by the insertion symbol string, whichever is farther to the left in the 
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PICTURE character string. The character positions preceding the insertion character 
are replaced with spaces. 


If all numeric character positions in the PICTURE character string are represented by 
the insertion character, the result depends on the value of the data. If the value is 0 
(zero) the entire data item contains spaces. If the value is not 0, the result is the same as 
when the insertion character is present only to the left of the decimal point. 


To avoid truncation, the minimum size of the PICTURE character string for the 
receiving data item must be the number of characters in the sending data item plus the 
number of nonfloating insertion characters being edited into the receiving data item plus 
one for the floating insertion character. 


Table 6-10 illustrates floating insertion editing. 


Table 6-10. Floating Insertion Editing Examples 


Editing Symbol in 
PICTURE Character String _ Data Item Actual Representation 


$$,$$$ 
-(5) 
~(5) 

++4+99 

+++99 


Zero-Suppression and Replacement Editing 
Zero-suppression editing can replace zeros either with spaces or with asterisks. 


The suppression of leading zeros in numeric character positions is indicated by the use 
of the symbol Z or the asterisk (*) as the suppression symbol in a PICTURE character 
string. These symbols are mutually exclusive in any PICTURE character string. Each ~ 
suppression symbol is counted in determining the size of the item. If the letter Z is used, 
the replacement character is the space; if the asterisk is used, the replacement character 
is the asterisk. 


Zero-suppression and replacement is indicated in a PICTURE character string by using a 
string of one or more allowable symbols to represent leading numeric character positions 
that are replaced when each associated character position in the data contains a zero. 

_ Any simple insertion characters embedded in the string of symbols or to the immediate 
right of this string are part of the string. | 
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In a PICTURE character string, zero-suppression can be represented in two ways: 


e Any or all leading numeric character positions to the left of the decimal point can be 
represented by suppression symbols. 


e Alinumeric character positions in the PICTURE character string can be represented 
by suppression symbols. 


If the suppression symbols appear only to the left of the decimal point, any leading zero 
in the data is replaced by the replacement character. Suppression ends at the first 
nonzero digit in the data represented by the suppression symbol string or at the decimal | 
point, whichever is encountered first. 


If all numeric character positions in the PICTURE character string are cenpeseatel by 
suppression symbols and the value of the data is not 0 (zero), the result is the same as if 
the suppression characters were located only to the left of the decimal point. ‘If the value 
of the data is the number 0 (zero) and the suppression symbol is Z, the entire data item 
consists of spaces. If the value of the data is 0 (zero) and the suppression symbol is an 
asterisk, then the data item consists of all asterisks except for the actual decimal point. 


The asterisk, when used as the zero-suppression symbol, cannot appear in the same 
entry as a BLANK WHEN ZERO statement. 


Table 6-11 illustrates zero-suppression and replacement editing. 


Table 6-11. Zero-Suppression and Replacement Editing Examples 


Picture . Actual Representation 


Editing Methods and Data Categories 


The type of editing that can be performed on an item depends on the category to which 
the item belongs. Table 6-12 specifies the type of editing that can be Periorned ona 
given item category. 
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Table 6-12. Data Categories and Editing Methods Allowed 


Category Type of Editing Allowed 


Alphabetic . Simple insertion using the space character 
(B) 


None 


Numeric 


Alphanumeric None 


Alphanumeric-edited Simple insertion using the space character 


| (B), the number O (zero) and the slash (/) 
Numeric-edited All (subject to the following note) 


Kanji None 


Kanji-edited Simple insertion using the space character 


(B), the number 0 (zero), and the slash (/) 


‘Note: Floating insertion editing and zero-suppression and replacement 


editing are mutually exclusive in a PICTURE clause. Only one type 
of replacement can be used with zero-suppression ina PICTURE — 
clause. | 


Editing Application of the PICTURE Clause 


6-24 


Table 6-13 provides various examples of the editing function of the PICTURE clause. 


Table 6-13. Editing Application of the PICTURE Clause 


Sending Area Receiving Area 


Editing PICTURE . 
PICTURE Clause Data Clause Edited Data 


9(5) $ZZ,279.99 $12,345.00 
v9(5) | 12345 $$$,$$9.99 | $0.12 


v9(5) 3 12345 $22,229.99 $ 0.12 
9(5) 00000 $$$,$$9.99 $0.00 
9(3)V99 12345 $ZZ,2Z9.99 $ 123.45 
(5) 00000 $35,385.58 


9(5) $$$,$$$.9$ $1,234.00 


continued 
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Table 6-13. Editing Application of the PICTURE Clause (cont.) 


Sending Area Receiving Area 


Editing PICTURE 
PICTURE Ciause Data Clause Edited Data 


9(5) 00000 
9(5) 00123 Gee wee oe $***123.00 
9(3)V99 00012 $ZZ,2Z9.99 $ 0.12 
9(3)v99 12345 $$$,$$9.99 $123.45 
9(3)V99 00001 $22Z,ZZZ.99 $ .01 
9(5) 12345 == $$$,$$9.99 $12,345.00 
9(5) 00000 $22,222.22 | 
9(3)V99 00001 $$$,$$$.$$ $.01 
$9(5) (+) 12345 22729.99+ 12345.00+ 
$95) oe (-) 00123 -99999,.99 -00123.00 
9(3)V99 12345 999.00 123.00 
$9(5) (-) 12345 ZZZZ9.99- 12345.00- 
$9(5) (+) 12345 2Z27Z9.99- 12345.00 
9(5) 12345 BBB99.99 45.00 
$9(5)V (-) 12345 -2Z729.99 -12345.00 
$9(5) (-) 12345 $$$$$$.99CR $12345.00CR 
$99V9(3) (-) 12345 ~.99 -12.34 


$** aR kK RRKKKKK KK 
’ . . 


$9(5) (+) 12345 $$$$$$.99CR $12345.00 
9(3)V99 12345 999.BB 123. 
9(5) 12345 00999.00 


00345.00 
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DATA DIVISION 


The third division of a source program, the DATA DIVISION, describes the data that the 
object program accepts as input to manipulate, create, or produce as output. Data to be 
processed falls into one of three categories: 


Data that is contained in files and that enters or leaves the internal memory of the 
computer from a specified area or areas 


Data developed internally and placed in intermediate or working storage or in a 
specific format for output-reporting purposes 


Constants that you define 


_ Sections of the DATA DIVISION 


The DATA DIVISION, one of the required divisions in a program, is subdivided into 
seven sections: 


The FILE SECTION defines the structure of data files. 


The DATA-BASE SECTION, a Unisys extension, describes one or more databases 
that can be used by the COBOL program. 


The WORKING-STORAGE SECTION describes records and noncontiguous data 
items that are not part of external data files but are developed and Paeeaene 
internally. 


The LOCAL-STORAGE SECTION, a Unisys extension, describes parameters to be 
received by separate tasks or by procedures to be bound from another program. 


The LINKAGE SECTION appears in the called program and describes data items to 
be referenced by the calling program and the called program. 


The COMMUNICATION SECTION describes the data items in the source program 
that serve as the interface between the data communications interface (DCD) library 
and the program. 


The REPORT SECTION describes the contents and format of generated formats. 


See Also 


For information about the REPORT SECTION, refer to Section 12, “Report Writer.” 


For information about the LINKAGE SECTION, refer to Section 13, “ANSI 
Inter-Program Communication (IPC).” 


For details about the COMMUNICATION SECTION, refer to Section 14, 
“COMMUNICATION SECTION.” 
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e For information about the DATA-BASE SECTION and the INVOKE clause, refer to 
| Volume 2 of this manual. 


e For information about the SAME RECORD AREA clause, refer to Volume 2 of this 
manual. 


The general structure of the DATA DIVISION is as follows. The sections FILE, 
WORKING-STORAGE, and LOCAL-STORAGE are explained on the following pages. 


DATA DIVISION. 


FILE SECTION. 
faeeeenearay) { record-description-entry | ... 
sort-merge-file-description-entry {record-description-entry} ...] 


| DATA-BASE SECTION. 
[ 01 [ internal-set-name ] INVOKE set-name ]... 


WORKING-STORAGE SECTION. 
[ 77-level-description-entry | 
[ record-description-entry | ... 


LINKAGE SECTION. 
| 77-level-description-entry 7 
[ record-description-entry | .. 


ee | 


[ record-description-entry | .. 


LOCAL-STORAGE SECTION. 
ae -storage-description-entry 
[ record-description-entry | .. | 


aaa description-entry 


igs COMMUNICATION SECTION. 


REPORT SECTION. 1 


{report-group-description-entry} .. 
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y 


FILE SECTION 


The FILE SECTION defines the structure of data files used in the program. These files 
have been previously named and assigned to a device in the SELECT clause. Typically, 
each file is defined by a file-description (FD) entry and one or more record descriptions. 
Record descriptions are written immediately following the FD entry. 


When the file description (FD) specifies a file to be used as a Report Writer output 
file, this file is defined by a FD entry, but no record-description entries are permitted. 
Report-description entries appear in the REPORT SECTION. 

File-Description (FD) Entry 
The file-description (FD) entry identifies a file previously declared in the SELECT clause 
and provides information about its physical structure. Record descriptions for the file 


immediately follow its file description. 


There are two formats for describing files. These formats are used as follows: 


Format Explanation 
1 _ This format describes input and output files. 
2 This format describes sort and merge files. 


8600 0296-000 7-3 


DATA DIVISION 


Format 1; File Description (FD) Entry 


FD file-name 


RECORDS — 
- BLOCK CONTAINS [| integer-1 TO ] integer-2 / BECORDS 
| aaa [ teger-1 TO | integer eae \ 


; RECORD CONTAINS [ integer-3 TO ] integer-4 CHARACTERS 
[ DEPENDING ON data-name-1] - 


| STANDARD | 
RECORD IS 
[ LABEL I eECOEDE ARE \ fama | 
= = See data-name-2 [, data-name-3] ... 


literal-1 


mnemonic-file-attribute-name IS mnemonic-attribute-value 
numeric-file-attribute-name 


pascaeapaera oe eed \ is oa 


mnemonic-file-attribute-name IS mnemonic-attribute-value 
; aie uae coeetgare I oe 
literal-2 


numeric-file-attribute-name 


RECORD IS 


‘DATA econ ARE 


} data-name-4 [ , data-name-5 ] .. | 


data-name-6 


; LINAGE IS i 
integer-5 


\ LINES 
| , WITH FOOTING AT ioe | 
integer-6 
data-name-8 
integer-7 } | 
data-name-9 
integer-8 } | 


| , LINES AT TOP { 


| , LINES AT BOTTOM { 


[ ; CODE-SET IS alphabet-name J. 
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Explanation of Format 1 


In a COBOL74 program, the file-description (FD) entry represents the highest level 
of organization in the FILE SECTION. The FILE SECTION header is followed by a 
file-description (FD) entry consisting of a level indicator (FD), a file-name, and a series 
of independent clauses. An FD identifies the beginning of a file description and must 
provide the file-name. 


The FD clauses specify the size of the logical and physical records, the presence or 
absence of label records, the value of file attributes, the names of the data records that 
make up the file, the character code set, the number of lines to be written on a logical. 
printer page, and the name or names of the reports pertaining to a given file. The 
clauses that follow the name of the file are optional in many cases, and their order of 
appearance is immaterial. The FD clauses are described on the following pages. 


One or more record description entries must follow the file-description (FD) entry, 
except when the REPORT clause in Report Writer is specified. 


Format 2: Sort Merge Description (SD) Entry 


SD file-name 


| sBLOCK CONTAINS | integer-1 TO ] integer-2 {uEconDS | 


CHARACTERS 
[ ; RECORD CONTAINS [ integer-1 TO | integer-2 CHARACTERS | 


RECORD IS 


I: DATA one ARE 


} data-name-1 [ , data-name-2 ].. | 


; VALUE OF 
{ mnemonic-file-attribute-name IS mnemonic-attribute-value 
{ alphanumeric-file-attribute-name } Is aia } 


numeric-file-attribute-name literal-2 


mnemonic-file-attribute-name IS mnemonic-attribute-value 
ahaxripee anniiaae eee aaa 
literal-2 


numeric-file-attribute-name 


Explanation of Format 2 


A sort merge description (SD) entry gives information about the size and names of the 
data records associated with the file to be sorted. No label procedures can be controlled 
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by users, and the rules for blocking and internal storage are peculiar to the SORT 
statement. 


The level indicator SD identifies the beginning of the sort-merge description entry and 
must precede the file-name. Other clauses that follow the name of the file are optional, 
and their order of appearance is immaterial. The SD clauses are described on the 
following pages. 


One or more record-description entries must follow the SD entry; however, no I/O 
statements (except RELEASE and RETURN) can be executed for this file. 
BLOCK CONTAINS Clause 


The BLOCK CONTAINS clause specifies the size of a physical record, also known as the 
blocking factor. 


This clause is required when the physical record contains more than one logical record. 
If this clause is not specified, the physical record is assumed to contain one logical record 
as large as the largest record specified for the file. (This is a Unisys extension.) 


This clause is not required in an SD file entry and has no effect on the SD file entry if 
specified. 


The general format of this clause is as follows: 


BLOCK CONTAINS [ integer-1 TO | integer-2 { 


RECORDS | 
CHARACTERS 


Explanation of Format 


If only integer-2 is shown, it represents the exact number of records or characters in the 
physical record. If integer-1 and integer-2 are both shown, they refer to the minimum 
and maximum size of the physical record, respectively. 


When the word RECORDS is not specified, the value of integer-2 must not be less than 
the largest record specified for the file. 


When RECORDS is specified, the physical record size is considered to be integer-2. 
multiplied by the size of the largest record specified for this file. 


When the word CHARACTERS is specified, the physical record size is considered to be 
integer-2. If integer-2 is not a multiple of the size of the largest record specified for the 
file, the physical record size is adjusted to be a multiple of the size of the largest record 
specified, not to exceed the value of integer-2. (This is a Unisys extension.) 


If logical records of differing sizes are grouped into one physical record, the amount of 
data transferred from the record area to the physical record depends on the size of the 
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record named in the WRITE or REWRITE statement. In this case, the logical records 
are aligned on maximum record-size boundaries. If the size of the record named does 
not equal the maximum record size specified for the file, the data is transferred to the 
physical record according to the rules specified for the MOVE statement without the 
CORRESPONDING phrase. The sending area is considered to be a group item. 


If variable-length records are specified, then the physical record size is determined as 
follows: 


e Ifthe word RECORDS is shown and only integer-2 is shown, the physical record size 
equals integer-2 multiplied by the maximum record size. 


e Ifthe word RECORDS is shown and integer-1 and integer-2 are both shown, the 
physical record size equals integer-1 multiplied by the maximum record size or 
integer-2 multiplied by the minimum record size, whichever is larger. 


e Ifthe word CHARACTERS is shown, the physical record size equals integer-2 or the 
maximum record size, whichever is larger. If the maximum record size is larger, a 
warning is issued. Integer-1 is shown for documentation only. 


In the case of relative file organization, the physical record size is adjusted by the I/O 


subsystem to be integer-2 multiplied by a value that is 6 bytes larger than that which 
would be determined by the previously stated methods. 


See Also 


e For more information about specifying record size, refer to “RECORD CONTAINS 
Clause,” in this section. 


e For information about record-blocking techniques, refer to the I/O Subsystem 
Programming Guide. 


RECORD CONTAINS Clause 


The RECORD CONTAINS clause specifies the size of the data records. It can be used to 
specify variable-length records. 


The general format of this clause is as follows: 


RECORD CONTAINS [ integer-3 TO | integer-4 CHARACTERS 


[ DEPENDING ON data-name-1 | 


Explanation of Format 
The DEPENDING ON clause is valid only if the integer-3 TO clause is present. The 


integer-3 TO clause is ignored for indexed or relative files; the DEPENDING ON clause 
is not allowed for indexed or relative files. 
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If the data-name-1 option is in the record of the file, then it must reference an 
elementary unsigned numeric item of USAGE IS DISPLAY (4 characters long) which is 
the first item in the record. If data-name-1 is not in the record of the file, then it must be 
an elementary unsigned numeric item. 


The size of each data record is completely defined in the record-description entry; 
therefore, the RECORD CONTAINS clause is never required. When this clause is 
present, however, the following rules apply: 


e For fixed-length records, use integer-4 alone when all data records in the file have 
the same size. In this case, integer-4 represents the exact number of characters in 
the data record. For fixed-length records, do not use the TO clause. 


e The record size is specified in terms of the number of character positions required 
to store the logical record, regardless of the types of characters used to represent 
the items in the logical record. The size of a record is determined by the sum of the 
number of characters in any variable-length item subordinate to the record. This 
sum can be different from the actual size of the record. 


e For variable-length records, integer-3 and integer-4 are both used. They refer, 
respectively, to the minimum number of characters in the smallest data record and 
the maximum number of characters in the largest data record. The following rules 
apply: 

— Ifthe DEPENDING ON clause is not specified, the logical-record length is 
supplied by the system and is written to the record as the first four characters of 
the record. This length cannot be referenced by the program. The format of the 
length depends on the USAGE value of the first 01-level record of the FD. For 
DISPLAY, the length is four EBCDIC characters; for COMP four packed decimal 
characters; for BINARY, one binary word. The length is part of the record when 
the type of the file is DISK or TAPE, but is not written if the file is REMOTE, 
PRINTER, PUNCH, or PORT. 


— Ifthe DEPENDING ON clause is specified, the logical-record length is supplied 
by the program at run time in data-name-1. Data-name-1 must follow the 
‘previously stated syntax rules. If data-name-1 is in the record, the logical-record 
length of data-name-1 must include the four bytes of data-name-1. 


—- WhenaREAD statement is executed, the contents of the data item referred to 
by data-name-1 indicate the maximum record size of the record just read. At 
end-of-file (EOF), data-name-1 is set to 0 (zero). 


LABEL RECORDS Clause 
The LABEL RECORDS clause specifies the presence or absence of label information. 


The general format of this clause is as follows: 


LABEL 


‘RECORD IS panna ee aie | 
RECORDS AREf )=———= 


data-name-1 [, data-name-2] ... 
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Explanation of Format 


STANDARD 


The STANDARD phrase should be used if you wish to take advantage of the automatic 
file allocation and handling procedures in the operating system. (Disk devices maintain a 
directory instead of a system of labels.) The format of labels is dependent upon the 
device containing the file. 


If the LABEL RECORDS clause is not used, the STANDARD phrase is assumed. 


OMITTED 


The OMITTED phrase must be used if an input file does not have standard labels. or if 
labels are not desired on output files. 


data-name-1 
All references to data-name-1 also apply to data-name-2 and so on. 


You should use the data-name-1 option to include header and trailer records in the 
standard tape label. This format can be used only with magnetic tape files. A maximum 
of nine label] records can be specified. 


Data-name-1 identifies the tape label user record descriptions to be used by the label 
USE procedures for a given file. The file handling routine of the operating system 
performs the USE statement when the file is opened, closed, or when a volume is 
switched. | 


Data-name-1 must be defined in the file-description (FD) entry for which it is defined or 
must be in the WORKING-STORAGE SECTION. The subordinate items identify the 
fields to be accessed in the label records and must add up to a total record size of 80 
characters. The first four characters of every label record are reserved for use by the 
operating system. 
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Example 


Example 7-1 shows a file-description (FD) entry with a LABEL RECORDS clause using 
the data-name-1 option. TAPE-LABEL is a record description in the file TAPE-FILE. 
The record description identifies the label to be used in the USE procedures. 


FD TAPE-FILE 
LABEL RECORD IS TAPE-LABEL 
VALUE OF FILENAME "TAPELABEL1" 
DATA RECORD IS TAPE-DATA. 

81 TAPE-LABEL. 


@3 LABEL-RESERVE PIC X(4). 
@3 DATE-OF-CREATION PIC 9(6). 
Q3 FORMAT-TYPE PIC XX. 

~ Q3 REMAINING-DATA PIC X(68). 


61 TAPE-DATA. 


Example 7-1. Coding the LABEL RECORDS Clause 


See Also 


e For information about the format of the USE procedures, refer to Format 2 of the 
USE statement in Section 9, “PROCEDURE DIVISION Statements.” 


e For information about label formats, refer to the J/O Subsystem Programming 
Guide. | 


VALUE OF Clause 
The VALUE OF clause defines the initial values for the attributes of a file. 


The descriptive clauses and phrases of the INPUT-OUTPUT SECTION and the file 
record descriptions (other than the VALUE OF clause) implicitly determine the initial 
values for appropriate attributes of a file. These attribute values, however, can be 
overridden, or other attributes can be specified, by the VALUE OF clause. 


Note: File attributes provide you with access to functionality not otherwise 
available within the language. Also, file attributes can be used to 
declare and access files. When both a file attribute and the standard 
COBOL syntax are available to accomplish a desired function, it 
is always preferable to use the standard COBOL syntax because 

_ changing the attribute can lead to unexpected results in cases when 
the attribute is also used or altered by the compiler. 


' This clause is not required in a sort merge description (SD), and has no effect on the sort 
merge description if specified. 


ap 
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The general format of this clause is as follows: 


numeric-file-attribute-name literal-1 
mnemonic-file-attribute-name IS mnemonic-attribute-value 
| | stan eben } is eas } | 
literal-2 


1 ceramn a IS mnemonic-attribute-value 


ee Is fot 


numeric-file-attribute-name 


Explanation of Format 


A mnemonic file attribute must be assigned amnemonic-attribute-value. An | 
alphanumeric or numeric file attribute can be assigned a value that is either a data-name 
or a literal. 


The mnemonic-attribute-value must be associated with the attribute specified. 
(Mnemonic-attribute-value is a Unisys extension.) 


If an alphanumeric file attribute is specified, literal-1, literal-2, and so on must be 
nonnumeric literals, and the identifier must be a nonnumeric DISPLAY data item. Ifa 
numeric file attribute is specified, the literal must be a numeric literal and the identifier 
must be a numeric data item that represents an integer. 


When an attribute is equated to a literal value, the value becomes a part of the 

file description given by the file when the file is first referenced at run time. Any 
specification in this file description (FD) can be overridden by a file equation. 

When an attribute is equated to a data-name value, the attribute is implicitly changed to 
this value just before execution of any explicit OPEN, SORT, or MERGE statement that 
references the file. 


Data-name-2, data-name-3, and so on can be qualified but cannot be subscripted or 
indexed. 


If an alphanumeric file attribute is specified, the contents of data-name must be followed 
by a period. 


File titles must not contain special characters. 
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Port Files 


Using data-name-2 in file descriptions for port files is not recommended for programs 
specifying subfiles that are to be opened independently and are to remain open 
simultaneously. The compiler explicitly sets all dynamic attributes for the entire file on 
each OPEN statement. An OPEN statement for a subfile of a port file is rejected by the 
operating system if any other subfile of the port file is open and if the file declaration 
contains a dynamic file attribute that can be modified only when the file is closed. 


Using the CHANGE statement is recommended for dynamically changing attributes 
of port files that have multiple subfiles explicitly opened. Note that the CHANGE 
statement must still be executed while the port file is closed. 


This restriction does not apply to programs that open the entire port file, to programs 
that have only one subfile of a port file open at any given time, or to file attributes that 
are not limited as to when they can be modified. 


Example 
Example 7-2 shows the coding of the VALUE OF clause. 


926008 FILE SECTION. 

828000 FD INFIL 

838080 LABEL RECORDS ARE STANDARD 
832088 VALUE OF FILENAME IS "TAPEIN" 


834288 SAVEFACTOR 39 
G36006 © AREAS IS 18 
038088 AREASIZE IS 1880. 


G49G02 O1 TAPE-REC PIC X(8@). 

8429068 FD WORK-FILE 

B44006 VALUE OF FAMILYNAME IS "PACK@1" 
846008 VALUE OF AREAS IS 28 

B48098 VALUE OF FILENAME IS "TEMP@1". 
858088 81 WORK-REC. 

B52088 ®5 KEY-REC PIC 9(8) COMP. 
B54986 @5 REM-WORK PIC X(76). 


Example 7-2. Coding the VALUE OF Clause 


See Also. 


e For general information about files, refer to Section 3, “File and Task Concepts.” 


e For more information about the CHANGE statement, a Unisys extension that 
enables you to modify a file attribute or a task attribute, refer to the CHANGE 
statement in Section 9, “PROCEDURE DIVISION Statements.” 


e Fora description of available attributes and their values, refer to the File Attributes 
Reference Manual. 


e For information about using file attributes, refer to the I/O Sinsaiee Programming 
Guide. 
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DATA RECORDS Clause - 


The DATA RECORDS clause is an optional clause that documents the names of data 
records associated with a file. 


_The general format of this clause is as follows: 


RECORD IS 
RECORDS ARE 


DATA \eRConDe 


8) data-name-4 [ , data-name-5 ] 


Explanation of Format 


Data-name-4 and data-name-5 are the names of data records that should have 01-level 
record descriptions (with the same names) associated with them. 


The presence of more than one data-name indicates that the file contains more than one 
type of data record. These records can be different (for example, in size or in format), 
and their listed order is not significant. 


Conceptually, all data records in a file share the same area, even if more than one type of 
data record is present in the file. 


Example 


Example 7-3 shows the coding of an FD and the DATA RECORDS clause. 


FD INPUT-FILE. 
DATA RECORDS ARE PRODUCTION, SALES, INVENTORY. 
$1 PRODUCTION. 


83 REC-TYPE-1 PIC 99. 

@3 REC-PROD PIC X(78). 
@1 SALES. 

83 REC-TYPE-2 PIC 99. 

83 REC-SALES PIC X(78). 
81 INVENTORY. 

83 REC-TYPE-3 PIC 99. 

83 REC-INVEN PIC X(78). 


_ Example 7-3. Coding the DATA RECORDS Clause 
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LINAGE Clause 


The LINAGE clause enables you to specify the number of lines per page, the size of the 
top and bottom margins on the logical page, and the line number within the page body at 
which the footing area begins. 


Each logical page is contiguous to the next; no additional spacing is provided. 


The general format of this clause is as follows: 


data-name-6 


LINAGE IS i 
integer-5 


} LINES 


WITH FOOTING AT foeiora \ 
eS integer-6 


data-name-8 i | 


, LINES AT TOP i 

——~— |[integer-7 

, LINES AT BOTTOM ones } 
“~~ Linteger-8 


Explanation of Format 


The LINAGE clause enables you to specify the size (number of lines) of a logical page. 
The logical page size is the sum of the values referenced by each phrase except the 
FOOTING phrase. If the LINES AT TOP or LINES AT BOTTOM phrase is not 
specified, the value for this function is 0. If the FOOTING phrase is not specified, the 
assumed value is equal to integer-5 or the contents of the data item referenced by 
data-name-6, whichever is specified. 


No particular relationship exists between the size of the logical page and the size of a 
physical page. 


LINAGE IS 


The value of integer-5 or of the data item referenced by data-name-6 specifies the 
number of lines that can be written, spaced, or both written and spaced on the logical 
page. The value must be greater than 0. The part of the logical page in which these lines 
can be written, spaced, or both written and spaced is called the page body. This value is 
used for all logical pages written for the file during a given execution of the program. Ifa 
‘WRITE ... ADVANCING PAGE statement is executed, or if a Page-Overflow condition 
occurs, the value specifies the number of lines for the next logical page. 


LINES AT TOP 
The value of integer-7 or of the data item referenced by data-name-8 specifies the 


number of lines desired for the top margin on the logical page. Integer-7 must be in the © 
range from 0 through 65,535. Ifthe value of data-name-8 is less than the number 0, 
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the results are unpredictable. Data-name-8 can be in the range from 0 through 
549,755,813,887. This value is used for all logical pages written for the file during a given 
execution of the program. Ifa WRITE ... ADVANCING PAGE statement is executed, 
or when a Page-Overflow condition occurs, the value specifies the top margin for the next 


logical page. 


LINES AT BOTTOM 


The value of integer-8 or of the data item referenced by data-name-9 specifies the 
number of lines desired for the bottom margin on the logical page. Integer-8 must be in 
the range from 0 through 65,535. If the value of data-name-9 is less than the number 

0, the results are unpredictable. Data-name-9 can be in the range from 0 through 

549, 755,813,887. This value is used for all logical pages written for the file during a given 
execution of the program. If a WRITE ... ADVANCING PAGE statement is executed, 
or if a Page-Overflow condition occurs, the value specifies the bottom margin for the next 


logical page. 


WITH FOOTING AT 


The value of integer-6 or of the data item referenced by data-name-7 specifies the line 
number in the page body at which the footing area begins. The value must be greater 
than 0, and less than or equal to the value of integer-5 or the data item referenced by 
data-name-6. 


The footing area consists of the area of the logical page between the line represented 
by the value of integer-6 or the data item referenced by data-name-7 and the line 
represented by the value of integer-5 or the data item referenced by data-name-6, 
inclusive. This value is used for all logical pages written for the file during a given 
execution of the program. If a WRITE ... ADVANCING PAGE statement is executed, 
or if a Page-Overflow condition occurs, the value specifies the footing area for the next. 


logical page. 


LINAGE-COUNTER Special Register 


The LINAGE-COUNTER, a special register, is generated by the presence of a LINAGE 
clause. The value in the LINAGE-COUNTER register at any time represents the line 
number at which the device is positioned in the current page body. The rules governing 
the LINAGE-COUNTER register are as follows: 


e Aseparate LINAGE-COUNTER register is supplied for each file described in the 
FILE SECTION that has a LINAGE clause. 


e The data-name, LINAGE-COUNTER, can be referenced, but not modified, by 
. PROCEDURE DIVISION statements. Because more than one LINAGE-COUNTER 
can exist in a program, you must qualify LINAGE-COUNTER by using a file-name 
when necessary. 
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e The LINAGE-COUNTER register is automatically modified according to the 
following rules during the execution of a WRITE statement to an associated file: 


- Ifthe ADVANCING PAGE phrase of the WRITE statement is specified, the 
_ LINAGE-COUNTER register is automatically reset to 1. 


~- Ifthe ADVANCING identifier-6 or integer phrase of the WRITE statement is 
specified, the LINAGE-COUNTER register is incremented by integer or by the 
value of the data item referenced by identifier-6. 


- Ifthe ADVANCING phrase of the WRITE statement is not specified, the 
LINAGE-COUNTER register is incremented by 1. 


— The value of the LINAGE-COUNTER register is automatically reset to 1 when 
the device is repositioned to the first line on which writing can occur for each of 
the succeeding logical pages. 


e The value of the LINAGE-COUNTER register is automatically reset to 1 when the 
file is opened. 


CODE-SET Clause 


The CODE-SET clause specifies the character code set ic to represent data on the 
external media. 


The general format of this clause is as follows: 


[| CODE-SET IS alphabet-name | 


7-16 © 


Explanation of Format 


If the CODE-SET clause is specified, alphabet-name specifies both the character code 
set used to represent data on the external media and the algorithm for converting the 
character codes on the external media to or from EBCDIC. This code conversion occurs 
during execution of an input or output operation. 


If the CODE-SET clause is not specified, the native character code set (EBCDIC) is 
assumed for data on the external media. 


When the CODE-SET clause is specified for a file, all data in that file must be described 
(because USAGE IS DISPLAY) and any signed numeric data must be described with the 
SIGN IS SEPARATE clause. 


The alphabet-name referenced by the CODE- SET clause must not specify the literal 
phrase. 


‘The CODE-SET clause can be specified only for files that are not ona mass-storage 


device. 
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See Also 


For information about specifying an alphabet-name, refer to “SPECIAL-NAMES” in 
Section 5, “ENVIRONMENT DIVISION.” 


Record Description 


One or more record descriptions must follow each file description (FD). A record 
description consists of a set of data-description entries that describe the characteristics 
of a particular record. Each data-description entry consists of a level-number (followed 
by a data-name, if required) followed by a series of independent clauses, as required. A 
record description has a hierarchic structure; therefore, the clauses used with an entry 
can vary considerably, depending on whether or not the entry is followed by subordinate 
entries. 


A data-description entry specifies the characteristics of a particular data item. The 
following four formats are used for the data-description entry: 


Format Use 
1 Defines a record. 
2 Renames entries. 
3 Specifies condition-names. 
4 


Invokes a dictionary. (Refer to Volume 2 for more information). 


See Also 


e For information about the structure of a record description, refer to “Levels” in 
Section 6, “Data Concepts.” 


e For information about the elements allowed in a record description, refer to “Data” 
in Section 6, “Data Concepts.” 
_Data-Description Entry for Record Structure 


The following general format shows the complete syntax for defining a sseand The 
optional clauses are described on the following pages. 


Note: Refer to Volume 2 for information about the USER and VERSION 
clauses. 
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Format 1: Record Structure 


level-number data-name-1 
FILLER 

[ ; REDEFINES data-name-2 | 

| +o 


IS character sg 


SHORT-DATE 
LONG-DATE CONVENTION OF ele 
NUMERIC-DATE USING x 
NUMERIC-TIME LANGUAGE oF { 
LONG-TIME 


| 


BINARY [ TRUNCATED | 
COMPUTATIONAL 
COMP 
CMP 
CONTROL-POINT 
CP 
DISPLAY 
EVENT 
INDEX 
LOCK 
TASK 
LEADING 
iS (ane } | SEPARATE CHARACTER | 
OCCURS | finteger-1 TO integer-2 TIMES DEPENDING ON data-name-5 
>10c integer-2 TIMES 
4 | EScENDING} KEY IS data-name-6 [ , data-name-7 ] ... | a 
{ INDEXED BY index-name-1 [ , index-name-2]. . .] 
SYNCHRONIZED LEFT 
SYNC | {RIGHT} 


data- -name-4 


e RIGHT | 


et IS literal-3 


TH on sornE \ 
LOWER-BOUNDS 
REFERENCE 
; RECEIVED BY ¢ REF 
, CONTENT 
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Explanation of Format 1 


The level-number can be any number from 01 through 49, or 77. Each record of a file 
begins with the level-number 01. This number is reserved for the record-name only, 
because it is the most inclusive grouping for a record. Less inclusive groupings are given 
higher numbers; these numbers are not necessarily successive. 


The clauses of the data-description entry can be written in any order, with the following 
exceptions: 


e The data-name-1 or FILLER clause must immediately follow the level-number. 
e The REDEFINES clause must immediately follow the data-name-1 clause. 


The PICTURE clause must be specified for every elementary item except an index data 
item. The PICTURE clause cannot be used for an index data item. 


The clauses SYNCHRONIZED, PICTURE, JUSTIFIED, and BLANK WHEN ZERO 
must not be specified except for an elementary data item. 


Multiple 01-level entries in a given file description (FD) of the FILE SECTION represent 
redefinition of the same memory area. 


If a file is selected using Format 5 of the SELECT statement, only record descriptions 
or form libraries invoked from the dictionary are allowed; record descriptions coded 

as usual are not permitted. If the file is not selected with Format 5 of the SELECT 
statement, then its record descriptions can ee either coded as usual or invoked from the 


dictionary. 


See Also 
e For more information about defining the hierarchic structure of a record, refer to 
“Levels” in Section 6, “Data Concepts.” 


e For Format 5 of the SELECT statement and for information about the rules and 
syntax for invoking the dictionary in order to use a previously defined data item, 
refer to Volume 2. 


Data-Name or FILLER Clause 


A data-name specifies the name of the data being described. The keyword FILLER 
specifies an elementary item of the logical record that cannot be referenced explicitly. 


The general format is as follows: 
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Explanation of Format 


In the FILE, COMMUNICATION, LINKAGE, and WOLiiING-STORAGE sections, a 
data-name or the keyword FILLER must be the first word following the level-number in 
each data-description entry. 


The keyword FILLER can be used to name an elementary item in a record. A FILLER 
item can never be referenced explicitly. However, the keyword FILLER can be used as a 
conditional variable because such use does not require explicit reference to the FILLER 
item, but instead requires reference to the value of the FILLER item. 


BLANK WHEN ZERO Clause 


This clause is used ee the PICTURE clause to print spaces if the value of ie data item 
is 0. 


The general format of this clause is as follows: 


BLANK WHEN ZERO 
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Explanation of Format 


The BLANK WHEN ZERO clause can be used only for an elementary item with the 
PICTURE clause specified as numeric or numeric-edited. — 


When the BLANK WHEN ZERO clause is used, the item contains nothing but bepacee if 
the value of the item is 0. 


When the BLANK WHEN ZERO clause is used for an item that has a numeric picture, 
the category of the item is considered to be numeric-edited. 


Example 


Example 7-4 illustrates the effect of the BLANK WHEN ZERO clause. 


Input File Output File 
PICTURE Data PICTURE Data 
Clause Clause 
9V99 ol) $.99 $00 
9V99 920 $.99 BLANK 

WHEN ZERO 


Example 7-4. Effect of the BLANK WHEN ZERO Clause 
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GLOBAL Clause (Unisys Extension) 


The GLOBAL clause allows COBOL programs compiled at lexicographic level 3 or higher 
to use untyped procedures, files, and certain variables in the outer block of the host 
program by declaring these items as global items. 


The general format of this clause is as follows: 


Explanation of Format 


Level-77 data items with BINARY, REAL, DOUBLE, EVENT, LOCK, or TASK usage, 
or 01-level items that are declared in the WORKING-STORAGE SECTION of a host 
program can be passed as parameters. These items can be declared global in a bound 
procedure by using the GLOBAL clause in the operand or item data-description entry. 
GLOBAL declarations are matched by name and type to the GLOBAL directory of the 
host. The GLOBAL clause must not be specified in the host program. 


Index-names generated for a global array are not themselves global items, but are 
treated as if they had been described with an OWN clause. ance name’ for a local array 
are treated as local variables. 


If most or all of the variables declared in the WORKING-STORAGE SECTION need to 
be declared global, the compiler control option GLOBAL can be used. The compiler 
control option can be assigned the value TRUE throughout the compilation, although 
this designation affects only variables that are candidates for GLOBAL declaration and 
that are in the WORKING-STORAGE SECTION. The LOCAL or OWN clause can be 
used to override the compiler control option. 


Examples 


| 
Example 7-5 shows how to declare data items to be global in the WORKING-STORAGE 
SECTION. 


77 GLASTATUS GLOBAL BINARY PIC 9(11). 
77 BL-EVENT GLOBAL EVENT. 
@1 GL-EBCRAY GLOBAL. 
. 3 CMP-ITM COMP PIC 9(11) OCCURS 1@@ INDEXED BY I. 


Example 7-5. Coding the GLOBAL Clause 


In Example 7-6, the GLOBAL compiler option declares G1, G2, and G3 to be global. L1 
is declared as local because the LOCAL clause overrides the GLOBAL compiler option. J 
is declared with an OWN clause because it is an index-name. 
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$ SET GLOBAL 


77 G1 BINARY PIC 9(11). 
77 G2 BINARY PIC 9(11). 
77 L1 LOCAL COMP PIC 9(11). 
G1 G3. 
3 FLD PIC 9(11) COMP OCCURS 1@ INDEXED BY J. 


Example 7-6. Using the GLOBAL Compiler Option 


JUSTIFIED Clause 
The JUSTIFIED clause changes the rules for alphanumeric move operations. Normally, 
data that is moved is left-justified. The JUSTIFIED clause causes alphanumeric data to 
be right-justified in the receiving data item. 


When the JUSTIFIED clause is omitted, the standard rules for data alignment in an 
elementary item apply. 


The general format of this clause is as follows: 


a STIFIED 


JUST } RIGHT 


Explanation of Format 
The JUSTIFIED clause can be specified only at the elementary item level. 
JUST is an abbreviation for JUSTIFIED. 


The JUSTIFIED clause cannot be specified for any data item described as numeric or for 
any data item for which editing is designated. 


When a receiving data item is described with the JUSTIFIED clause and the sending 
data item is larger than the receiving data item, the leftmost characters are truncated. _ 
When the receiving data item is described with the JUSTIFIED clause and is larger than 


the sending data item, the data is aligned at the rightmost character position i in the data 
item with space-fill for the leftmost character positions. 


See Also 


For information about data alignment, refer to Section 6, “Data Concepts.” 
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LOCAL Clause (Unisys Extension) 


A local data-name is referenced in the same procedure in which it is declared. Any value 
stored in it is lost upon exit from that procedure. 


‘The general format of this clause is as follows: 


LOCAL 


In COBOL procedures compiled at level 3 or higher, data-names are implicitly declared 
as local unless the GLOBAL or the OWN clause is specified. 

LOWER-BOUNDS Clause (Unisys Extension) 
The LOWER-BOUNDS clause permits bound or host COBOL74 programs to pass or 
receive array parameters compatible with the FORTRAN and ALGOL constructs that 


generate a lower-bound stack item. 


The general format of this clause is as follows: 


WITH { 


LOWER-BOUND 
LOWER-BOUNDS 


Explanation of Format 


This clause is used in the data description of a 01-level item in the LINKAGE SECTION 
(if array parameters are received) or the LOCAL-STORAGE SECTION (if array 
parameters are to be passed). 


The LOWER-BOUNDS clause is not meaningful for 77-level items. A warning is issued 
if a 77-level data item is declared with the WITH LOWER-BOUNDS clause. 


The LOWER-BOUNDS clause affects only bound procedures. The purpose of this 
clause is to declare formal parameters for binding that are compatible with FORTRAN 
and ALGOL. The clause must always be used when communicating with FORTRAN 
programs and must be used when communicating with ALGOL programs that contain 
formal array parameters declared with a variable lower-bound description (that is, 
ARRAYNAME [*]). The actual lower-bound parameter passed by a COBOL program to 
another program always has a value of 0. 


The actual lower-bound parameter received by a COBOL program is not used in 
addressing the array. 
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Table 7-1 shows the matching of parameters Derween the COBOL74 and ALGOL 
programming languages. 


Table 7-1. COBOL74 and ALGOL Parameter Matching 


COBOL Parameter | Corresponding ALGOL Parameter 


01 BINARY REAL array [<integer>] 
01 BINARY WITH LOWER-BOUNDS REAL array [*] 


01 COMP . EBCDIC character array [<integer>] 
01 COMP WITH LOWER-BOUNDS EBCDIC character array [*] 


01 DISPLAY EBCDIC character array [<integer>] 
01. DISPLAY WITH LOWER-BOUNDS EBCDIC character array [*] 


01 DOUBLE REAL array [<integer>] 
01 DOUBLE WITH LOWER-BOUNDS REAL array [*] 


01 REAL REAL array [<integer>] 
01 REAL WITH LOWER-BOUNDS REAL array [*] 


Note: The <integer> variable, in ALGOL, is the specified lower-bound 
parameter. 


For library calls and tasking calls, the LOWER-BOUNDS clause is ignored. 


For COBOL74 tasks, parameters with or without lower-bounds can be passed to 
COBOL74 programs and received from COBOL74 programs; the operating system 
handles the coercion. COBOL74 does not use the value of the lower-bound parameter in 
addressing the array. 


' When a user program passes an array parameter with a lower-bound to a COBOL74 


library, the user program actually sends two parameters: a by-reference array followed 
by a by-value integer. The COBOL74 program must declare an extra parameter, a 
77-level PIC 9(11) BINARY item, to receive the lower-bound parameter. 


OCCURS Clause 
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The OCCURS clause defines tables and other homogeneous data items. If the OCCURS 
clause is used, the data-name that is the subject of this entry must be either subscripted 
or indexed whenever it is referenced in a statement other than the SEARCH or USE 
FOR DEBUGGING statement. In addition, if the subject of this entry is the name of a 
group item, then all data-names belonging to the group must be subscripted or indexed 
whenever they are used as operands, except when the data-names are the objects of a 
REDEFINES clause. 
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The OCCURS clause eliminates the need for separate entries for repeated data items 
and supplies information required to apply subscripts or indexes. 


Except for the OCCURS clause itself, all data-description clauses associated with an 
item that has an OCCURS clause in its description apply to each occurrence of the item 
described. 


The OCCURS clause has the following two formats: 


Format | Explanation 
1 Specifies that an item occurs an exact number of times. 
2 Specifies that an item occurs a variable number of times, depending on 


the data item referenced by data-name-1. 


Format 1 
The general format of this clause is as follows: 


{ocouRs 


OC \ integer-2 TIMES 


ASCENDING 
DESCENDING 


} KEY IS data-name-2 [ , data-name-3 ] ss 


[ INDEXED BY index-name-1 [ , index-name-2 ] ...] 


Explanation of Format 1 


Format 1 of the OCCURS clause cannot be specified in a data-description entry that 
meets either of the two following conditions: 


e The entry has a 01, 66, 77, or 88 level-number. 


e The entry describes an item of variable size. The size of an item is considered 
variable if the data description of any subordinate item contains Format 2 of the 
OCCURS clause. 


OCCURS or OC 


' OC is an abbreviation for OCCURS. (This is a Unisys extension.) 


integer-2 


Integer-2 cannot exceed the maximum record size. 
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KEY IS — 


The KEY IS phrase indicates that the repeated data is arranged in ascending or 
descending order according to the values contained in data-name-2 and data-name-3. 
The data-names are listed in descending order of significance. 


Data-name-2 and data-name-3 can be qualified. 


INDEXED BY 


An INDEXED BY phrase is required if the subject of the entry or an entry subordinate 
to this entry is referenced by indexing. The index-name identified by this clause is not 
defined elsewhere because its allocation and format depend on the hardware, and the 
index-name cannot be associated with any data hierarchy because it is not a data item. 


Index-name-1 and index-name-2 must be unique words in the program. 


Note: When the OCCURS clause is used on a group item, the sum of the 
number of index-names in any associated INDEXED BY clause and 
the number of data-names declared subordinate to the group item 
cannot exceed 511. 


Format 2 


The general format of this clause is as follows: 


ae 


Oc } integer-1 TO integer-2 TIMES DEPENDING ON data-name-1 


| \GESCENDT G 


DESCENDING} Se ee ener 2 eee eet dl 


[ INDEXED BY index-name-1 [ , index-name-2 ] ...] 


Explanation of Format 2 


Format 2 specifies that the subject of this entry has a variable number of occurrences. 
The value of integer-2 represents the maximum number of occurrences, and the value of 
integer-1 represents the minimum number of occurrences. The length of the subject of 
the entry is not variable, but the number of occurrences is variable. 


A data-description entry that contains Format 2 of the OCCURS clause can be followed 
in that record description only by data-description entries that are subordinate to it. 
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integer-1 TO integer-2 


~ The value of integer-1 must be less than the value of integer-2. Integer-1 and integer-2 
cannot exceed the maximum record size. A syntax error results if the limit is exceeded. 


DEPENDING ON 


The value of data-name-1 is used to determine the last table element that can be 
referenced. When the value of data-name-1 is less than integer-2, the data items with 
occurrence numbers exceeding the value of data-name-1 are inaccessible. Reducing the 
value of the data item referenced by data-name-1 has no effect on the contents of data 

_ items with occurrence numbers that exceed the value of the data item referenced by 

. data-name-1. (This is a Unisys extension.) 


When a table element is referenced, the value of data-name-1 must fall in the range 
integer-1 through integer-2, inclusive. If the value of data-name-1 is outside this range, 
_the program ends abnormally. 


Data-name-1 can be qualified. 


The data description of data-name-1 must be that of an unsigned integer. Integer-1 can 
be 0, which is a relaxation of the ANSI-74 standard rule requiring a minimum of one 
occurrence. If data-name-1 takes on a value of 0 at run time, then no occurrences exist 
until the value of data-name-1 becomes nonzero. Any attempt to refer to an occurrence 
outside the current range produces an error. 


The data item defined by data-name-1 must not occupy a character position in the range 
between the first character position defined by the data-description entry containing the 
OCCURS clause and the last character position defined by the record-description entry 
containing that OCCURS clause. 


KEY IS 
If data-name-2 is not the subject of this entry, then the following three conditions apply: 
e Allitems identified by the data-names in the KEY IS phrase must be in the group 


item that is the subject of this entry. 


e Items defined by the data-name in the KEY IS phrase must not contain an OCCURS 
clause. 


e Noentry can contain an OCCURS clause between the items identified by the 
data-names in the KEY IS phrase and the subject of this entry. 


When a group item is referenced that has a subordinate entry that uses Format 2 of the 
OCCURS clause, only that part of the table area specified by the value of data-name-1 is 
used in the operation. 


The KEY IS phrase indicates that the repeated data is arranged in ascending or 


descending order according to the values contained in data-name-2 and data-name-3. 
The data-names are listed in descending order of significance. 
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Data-name-2 and data-name-3 can be qualified. 


INDEXED BY 


An INDEXED BY phrase is required if the subject of the entry or an entry subordinate 
to this entry is referenced by indexing. The index-name identified by this clause is not 
defined elsewhere because its allocation and format depend on the hardware, and the 
index-name cannot be associated with any data hierarchy because it is not a data item. 


Index-name-1 and index-name-2 must be unique words in the program. 


Note: When the OCCURS clause is used on a group item, the sum of the 
number of index-names in any associated INDEXED BY clause and 
the number of data-names declared subordinate to the group item 
cannot exceed 511. 


OWN Clause (Unisys Extension) 


COBOL procedures compiled at level 3 or higher can declare certain variables to be 
OWN. These variables retain their values or states throughout repeated exits and 
reentries of the procedure in which they are declared. 


The general format of this clause is as follows: 


Any item declared in the WORKING-STORAGE SECTION can be made OWN by using 
the OWN clause or the compiler control option OWN. 


All related index-names and copy descriptors for OWN items are also OWN; redefinitions 
of OWN items are implicitly OWN and need not use the OWN clause. 


Use of the compiler control option OWN throughout the compilation causes all stack 
locations obtained in the WORKING-STORAGE SECTION to be OWN, unless 
overridden temporarily by a GLOBAL or LOCAL clause on an individual item. 


Example 


Example 7-7 shows the declaration of OWN data items in the WORKING-STORAGE 
SECTION. 


77 X PIC X(1@) OWN. 
77 Y REDEFINES X PIC 9(1@). 
81 A OWN. 
@3 CMP-ITEM COMP PIC 9(11) OCCURS 188 INDEXED BY J. 


Example 7-7. Coding the OWN Clause 
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PICTURE Clause 


The PICTURE clause describes the type of data item, the size of a data item, and the 
editing requirements of an elementary data item. 


The following two methods exist for performing editing with the PICTURE clause: 


e Insertion editing 


e Zero-suppression and replacement editing 


The general format of the PICTURE clause is as follows: 


PICTURE 


PIC IS character string 
PC 


Explanation of Format 

A PICTURE clause can be specified only at the elementary item level and must be 
specified for every elementary data item except an index data item. The PICTURE 
clause cannot be specified for an index data item. : 


A character string consists of certain allowable combinations of characters in the COBOL 
character set that are used as symbols. The allowable combinations determine the 
category of the elementary item. The maximum number of characters allowed in the 
character string is 30. 


PIC and PC are abbreviations for PICTURE. (PC is a Unisys extension.) 


The asterisk, when used as the zero-suppression symbol, and the clause BLANK WHEN 
ZERO cannot appear in the same entry. 


See Also 


Insertion editing and zero-suppression and replacement editing are described in Section 
6, “Data Concepts.” . 


Defining Data Categories. 
The following seven categories of data can be described with a PICTURE clause: 
alphabetic, numeric, alphanumeric, alphanumeric-edited, numeric edited, Kanji, and 
Kanji-edited. 


Table 7-2 shows the rules for defining the seven categories of data. — 
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Table 7-2. Defining Items with the PICTURE Clause 


Data Type Rules for Defining the Data Type 


Numeric The character string can contain only the symbols P, S,.V, and 9. The 
number of digit positions that can be described by the character string 
must be from 1 to 23. 


If unsigned, the contents of the item (when represented in standard data 
format) must be a combination of the numerals 0 through 9; if signed, 
the item can also contain a plus sign (+), a minus sign (—), or any other 
representation of an operational sign. 


Alphabetic The character string of the item can contain only the symbols A and B. 


The contents of the item (when represented in standard data format) 
must be a combination of the 26 letters of the alphabet and the space 
from the COBOL character set. 


The character string of the item is restricted to certain combinations of 
the symbols A, X, and 9; the item is treated as if the character string 
contained all Xs. A PICTURE character string that contains all As or 9s 
does not define an alphanumeric item. 


Alphanumeric 


The contents of the item (when represented in standard data format) are 
allowable characters in the character set. 


Alphanumeric- | The character string is restricted to certain combinations of the symbols 
edited A, B, X, 9, 0 (zero), and slash (/). In addition, one of two conditions 
must apply as follows: 


e The character string must contain at least one B and one X, at least 
one O (zero) and one X, or at least one slash (/) and one X. 


e@ The character string must contain at least one 0 (zero) and one A, 
or at least one slash and one A. 


The contents of the item (when represented in standard format) are 
allowable characters in the character set. 


Numeric-edited The character string of the item is restricted to certain combinations of — 
the symbols B, P, V, Z, 9, 0 (zero), slash (/), comma (,), period (.), plus 
sign (+), minus sign (-), CR, DB, asterisk (*) and dollar sign ($). The 
allowable combinations are determined from the order of precedence of 
symbols and the editing rules. in addition, both of the following 
conditions must apply: 


e@ The number of digit positions that can be represented in the 
character string must be from 1 through 23. 


e The character string must contain at least one B, Z, O (zero), slash 
(/), comma (,), period (.), plus sign (+), minus sign (~), CR, DB, 
asterisk (*), or dollar sign ($). 


The contents of the character positions of symbols that are allowed to 
represent a digit in standard data format must be one of the numerals. 


continued 
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Table 7-2. Defining Items with the PICTURE Clause (cont.) 


Data Type Rules for Defining the Data Type 


The character string can contain only the symbol X. 


The contents of the item (when represented in standard data format) are 
represented in a 2-byte (16-bit) format. 


Kanji-edited The character string of the item is restricted to certain combinations of 
the symbols X, B, O (zero), and slash (/). In addition, the character string 
must contain at least one B and one X, at least one O (zero) and one X, 
or at least one slash (/) and one X. 


The contents of the item (when represented in standard format) are 
represented in a 2-byte (16-bit) format. 


See Also 


For information about specifying an operational sign for numeric data, refer to “SIGN 
Clause” later in this section. 


Determining the Size of the Elementary Item 


The size of an elementary item is the number of character positions it occupies in 
standard data format. You indicate the size of an elementary item by using the number 
of allowable symbols that represent character positions. For example, 9999 indicates a 
field with four digits. 


The symbols A, B, B X, Z, 9, 0 (zero), slash (/), plus sign (+), minus sign (—), asterisk 
(*) or dollar sign ($) can appear more than once in a given PICTURE clause. You can 
specify a number of consecutive occurrences of a symbol by using an integer enclosed 
in parentheses after the symbol. For example, X(8) indicates eight eiphanumers: 
characters. 


Using Symbols to Describe Data 
Table 7-3 provides a brief description of the functions of each symbol used to describe an 


elementary item. Refer to Section 6, “Data Concepts,” for a complete description of the 
purpose of each symbol. . 
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Table 7-3. Using Symbols to Describe Elementary Items 


Symbol Meaning . . 


X Alphanumeric field 


Numeric field 
Alphabetic field 


Assumed decimal point; used only in numeric fields 


Operational sign; used only in numeric fields 
; Decimal scaling position; used only in numeric fields 
Zero-suppression symbol 
Period 


Plus sign 
Minus sign 
Dollar sign or currency symbol 
Comma 
Credit symbol 
Debit symbol 


Check protection symbol 
Space insertion character or field separator 


Zero insertion character 


Slash character 


The following symbols can appear only once in a given PICTURE clause: 


e § 

e V 

e . (period) 
e CR 

e DB 


Understanding Precedence Rules 


7-32 


The chart in Figure 7~1 shows the order of precedence when characters are used as 
symbols in a character string. An X at an intersection indicates that the symbol or 
symbols at the top of the column can precede the symbol or symbols left of the row in a— 
character string. Arguments appearing in braces indicate that the symbols are mutually 
exclusive. 
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At least one of the symbols A, X, Z, 9, or asterisk (*), or at least two of the symbols, plus 
sign (+), minus sign (—), or dollar sign ($), must be present ina PICTURE string. 


Nonfloating insertion symbols plus sign (+), minus sign (—), and floating insertion 
symbols Z, asterisk (*), plus sign (+), minus sign (—) and dollar sign ($), and another 
symbol P appear twice in Figure 7-1. The leftmost column and uppermost row for 
each symbol represent the use of the symbol to the left of the decimal point position; 
the second appearance of the symbol in the chart represents its use to the right of the 
decimal point position. 


Nonfloating Insertion Floating Insertion 
ymbols Symbols Other Symbols 
Second CR Z u 
Symbo] DB 


c 
°o 
- 
ee) 
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“ 
i= 
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i=)) 
= 
_- 
wa) 
© 
o 
pone 
qe 
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i?) 
= 


“" 
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Floating Insertion 


epbhehe ep ee Ey 


Other Symbols 


ff fet et t=] Et ft fle p 


Figure 7-1. PICTURE Character Precedence Chart 
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RECEIVED Clause (Unisys Extension) 


7-34 


The RECEIVED clause identifies those items that are received as parameters by name 
or by value from another procedure, or items that are to be passed to another procedure 
by name. 


The general format of this clause is as follows: 


REFERENCE 
RECEIVED BY {Rar 


CONTENT 


Explanation of Format 


The RECEIVED clause can appear only on a 77-level data item in the 
LOCAL-STORAGE, LINKAGE, or WORKING-STORAGE SECTION. 


When you do not specify the RECEIVED BY clause, all items and files are received by 
reference to bound procedures except for 77-level parameters with the following usage: 
BINARY, DOUBLE, or REAL. For bound procedures, these parameters are received by 
content. However, you can declare these parameters to be received by reference to allow 
passing by reference. For tasking calls, 77-level parameters with BINARY, DOUBLE, or 
REAL usage can be declared as received by content to allow passing by value. 


A data-description entry containing the RECEIVED clause must not contain a VALUE 
clause. . 


RECEIVED BY REFERENCE 


The RECEIVED BY REFERENCE clause allows two or more procedures to share an 
item. Any reference to the identifier in one of the procedures that shares the identifier 
specifies the same common data area as the other procedures. REF is synonymous with 
REFERENCE. 


RECEIVED BY REFERENCE 77-level items with BINARY, DOUBLE, or REAL 

usage are a special case of parameter passing. Parameters declared in this way refer 
to data declared in the hardware stack on A Series systems. All other RECEIVED 

BY REFERENCE parameters address items within an array. This special case of the 
RECEIVED BY REFERENCE clause allows COBOL74 programs to communicate with 
ALGOL programs and other COBOL programs that pass stack references instead of 
array references. 


RECEIVED BY CONTENT 


This clause identifies parameters passed by value. The current value of the identifier 
is received by procedure. Another procedure can change the value of that data-name, 
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but the change merely affects the copy of the item for that procedure. Likewise, the 
receiving procedure can make changes to data-names that do not affect the original item. 


The RECEIVED BY CONTENT clause cannot appear with any item that has usage 
described as TASK (CONTROL-POINT), EVENT, or LOCK or with any item described 
at the 01-level. 


If an item declared as RECEIVED BY CONTENT is referred to ina PROCEDURE 
DIVISION USING declaration, the program cannot be used as a library and cannot be 
the subject of an Inter-Program Communication (IPC) CALL statement. The program 
can be used as a bound procedure, or it can be called from the Work Flow Language 
(WFL). 


REDEFINES Clause 
The REDEFINES clause allows the same computer storage area to be described by 
different data-description entries. This clause redefines the storage area, not the data 


items occupying the area. 


The general format of this clause is as follows: 


level-number datespamect: REDEFINES data-name-2 


Note: Level-number, data-name-1, and the semicolon () are shown 
for clarity. Level-number and data-name-1 are not part of the 
REDEFINES clause. 


Explanation of Format 


The REDEFINES clause, when specified, must immediately follow data-name-1. The 
level-numbers of data-name-1 and data-name-2 must be identical but must not be 66 or 
88. 


The clause must not be used in 01-level entries in the FILE SECTION or 
COMMUNICATION SECTION. The REDEFINES clause can be used at the 01-level in 
the WORKING-STORAGE SECTION. 


The data-description entry for data-name-2 cannot contain a REDEFINES clause. 
However, data-name-2 can be subordinate to an entry that contains a REDEFINES 
clause. In addition, the data-description entry for data-name-2 cannot contain an 
OCCURS clause; however, data-name-2 can be subordinate to an item that has an 
OCCURS clause in its data-description entry. In this case, the reference to data-name-2 
in the REDEFINES clause cannot be subscripted or indexed. Neither the original 
definition nor the redefinition can include an item of variable size as defined in the 
OCCURS clause. 
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No entry with a level-number numerically lower than the level-number of data-name-2 
and data-name-1 can occur between the data-description entries of data-name-2 and 
data-name-1. 


Redefinition starts at data-name-2 and ends when a level-number less than or equal to 
that of data-name-2 is encountered. 


Multiple redefinitions of the same character positions are permitted. The entries giving 
the new descriptions of the character positions must follow the entries for the area being 
redefined, without intervening entries that define new character positions. Multiple 
redefinitions of the same character positions must all use the data-name of the entry that 
originally defined the area. 


The entries that give the new description of the character positions must not contain any 
VALUE clauses except in condition-name entries. 


Multiple 01-level entries subordinate to any given level indicator represent implicit 
redefinitions of the same area. 


The following paragraphs refer to Unisys extensions. 


The REDEFINES clause specifies the redefinition of a storage area, not the data items 
occupying the area. Therefore, the usage of data-name-1 need not be the same as 

the usage of data-name-2, except that DISPLAY or group data items cannot redefine 
elementary COMPUTATIONAL or INDEX data items that do not begin on a byte 
boundary. When redefinition occurs at a level other than the 01-level, the amount of 
storage allocated for data-name-2 must be the same as the amount of storage implied by 
the declared size and usage of data-name-1, with the following exceptions: 


e ADISPLAY or group data item can redefine an elementary COMPUTATIONAL 
data item that begins, but does not end, on a byte boundary if the difference in size 
results from the generation of a 4-bit filler so that the redefining item ends on a byte 
boundary. 


e ADISPLAY or group item can be redefined by an elementary COMPUTATIONAL 
data item, although the actual size (including sign position, if described) is one 
4-bit character less than the number of 4-bit characters in the storage area. The 
redefining item is aligned to begin on a byte boundary and end at the middle of the 
last byte of storage. 


See Also 


Refer to Volume 2 for information about using the REDEFINES clause with form 
libraries. 
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SIGN Clause 


The SIGN clause specifies the position and mode of representation of the operational 
sign when these properties must be described explicitly. 


The general format of this clause is as follows: 


LEADING 


[ SIGN 18 ] coins 


} [ SEPARATE CHARACTER | 


Explanation of Format 


SIGN 


The optional SIGN clause specifies the position and mode of representation of the 
operational sign for the numeric data-description entry to which the clause applies or for 
each numeric data-description entry subordinate to the group to which the group applies. 
The SIGN clause applies only to numeric data-description entries with the character S in 
the PICTURE clause. The letter S indicates the presence of, but not the representation 
or position of, the operational sign. 


A numeric data-description entry with an S in the PICTURE clause, but to which no 
optional SIGN clause applies, has an operational sign that is positioned and represented 
according to the standard default position and representation of operational signs. 


Every numeric data-description entry with the character S in the PICTURE clause is 
a signed, numeric data-description entry. If a SIGN clause applies to such an entry 
and conversion is necessary for computation or comparisons, conversion takes place — 
automatically. 


The SIGN clause can be specified only for a numeric data-description entry with the 
character S in the PICTURE clause or for a group item Contaning at least one such 
numeric data-description entry. 

The numeric data-description entries to which the SIGN clause applies must be 
described as USAGE IS DISPLAY or USAGE IS COMPUTATIONAL. (Use of the SIGN 
clause with USAGE IS COMPUTATIONAL is a Unisys extension.) 


At most, one SIGN clause can apply to any given numeric data-description entry. 
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If a SIGN clause without a SEPARATE CHARACTER phrase applies to a numeric 
data-description entry, then the following rules apply: 


© When the data-item usage is DISPLAY, the operational sign is maintained and 
expected as binary number 1100 or 1101 in the zone of the leading or trailing 
character and does not cause additional storage to be allocated for the data item. 


e Ifthe data-item usage is COMPUTATIONAL, the operational sign is maintained and 
expected as binary number 1100 or 1101 leading or trailing 4-bit character. This sign 
increases by one 4-bit character the amount of storage allocated for the data item, in 
addition to that storage allocated for an unsigned COMPUTATIONAL data item. 
The presence or absence of the SEPARATE CHARACTER phrase has no effect on 
the position or representation of the operational sign for COMPUTATIONAL data 
items. 


SEPARATE CHARACTER 


If the CODE-SET clause is specified, any signed numeric data-description entries 
associated with that file must be described with the SIGN IS SEPARATE clause. 


If a SIGN clause with a SEPARATE CHARACTER phrase applies to a numeric 
data-description entry, then the following rules apply: 


e If data-item usage is DISPLAY, the operational sign is maintained and expected as a 
leading or trailing character separate from, and in addition to, the numeric character 
positions. The operational sign for negative values is the minus sign (—) and for 
nonnegative values is the plus sign (+). 


e When the data item usage is COMPUTATIONAL, the operational sign is maintained 
and expected as a binary 1100 for positive values or a binary 1101 for negative values 
in the zone of the leading or trailing character. The sign increases by one 4-bit 
character the amount of storage allocated for an unsigned COMPUTATIONAL 
data item. The binary number 1111 is also allowed as a positive value because 
any combination that is neither 1101 nor a digit is interpreted by the hardware as 
positive. The operators produce 1100 for a positive sign and 1101 for a negative sign. 
The SEPARATE CHARACTER phrase does not affect the position or representation 
of the operational sign for COMPUTATIONAL data items. - 


SYNCHRONIZED Clause 


. The SYNCHRONIZED clause specifies the alignment of an elementary item on the 
natural boundaries of the computer memory. 


The general format of this clause is as follows: 


a | jes 


SYNC RIGHT 
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Explanation of Format 

This clause can aaa only with an elementary item. 

SYNC is an abbreviation for SYNCHRONIZED. 

This clause cannot appear with items of type INDEX, TASK, EVENT, or LOCK. 


If the subject data item is of type COMPUTATIONAL, it is aligned on a byte boundary. 
If the data item is a BINARY type, it is aligned on a word boundary. If the previous 
data item did not end on a byte (or word) boundary, an implicit FILLER keyword is 
generated. This unused FILLER keyword is included in the size of any group item or 
items to which the elementary item belongs. 


The RIGHT or LEFT option following SYNCHRONIZED is treated as a comment entry. 


Whenever a SYNCHRONIZED item is referenced in the source program, the original 
size of the item, as shown in the PICTURE clause, is used in determining any action that 
depends on size, such as justification, truncation, or overflow. 


If the data description of an item contains the SYNCHRONIZED clause and an 
operational sign, the sign of the item appears in the normal operational sign position, — 
regardless of whether the SYNCHRONIZED LEFT or SYNCHRONIZED RIGHT clause 
is used with the item. 


BINARY, DOUBLE, and REAL data items subordinate to a data-description entry 
containing an OCCURS clause are not synchronized. 


In all other cases, when the SYNCHRONIZED clause is specified in a data-description 
entry of a data item that also contains an OCCURS clause, or in a data-description entry 
of a data item subordinate to a data-description entry containing an OCCURS clause, the 
following rules apply: 


e ach occurrence of the data item is synchronized. 


e Any implicit FILLER keyword generated for other data items in that same table is 
generated for each occurrence of those data items. 


TYPE Clause (Unisys Extension) 
The TYPE clause provides automatic date and time editing based on the CONVENTION 


option, LANGUAGE option, or CONVENTION and LANGUAGE options you specify. 
This clause can be used only for internationalization purposes. 
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The general format of the TYPE clause is as follows: 


SHORT-DATE 
LONG-DATE 
NUMERIC-DATE 
NUMERIC-TIME 
LONG-TIME 


CONVENTION OF ae } 
data-name-3 


literal-2 } 
data-name-4 


USING 
LANGUAGE OF { 


Explanation of Format 


Data items can be declared to be one of the following date or time types: 


Type Example 

SHORT-DATE Fri, Aug 31, 1990 

LONG-DATE Friday, August 31, 1990 
NUMERIC-DATE 08/31/90 

NUMERIC-TIME 13:37:20 

LONG-TIME 14 hours 37 minutes 20 seconds 


Data items can also be declared with an associated LANGUAGE or CONVENTION 
option. 


Each convention defined by Unisys has a specified format for the five date or time 

data items. The program formats an item declared to be one of the five date or 

time types according to the predefined format of the specified convention. For the 
SHORT-DATE, LONG-DATE, and LONG-TIME options, the specified language is also 
used in formatting the output. If the convention or language is not specified, the system 
determines the language, the convention, or the language and convention to be used 
based on system-defined hierarchy. 


The only clauses that can be used with the TYPE clause are the PICTURE clause and 
the USAGE clause. If the USAGE clause is specified, it can only designate USAGE IS 
DISPLAY. If the date or time items are edited in the PICTURE clause, the TYPE clause 
overrides the edit and the compiler issues a warning message. . 


_ The total length of the data item must be greater than or equal to the length required by 


the format of the specified convention. If the length of a data item is shorter than the 
required length, the compiler issues a truncation warning message. 
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Example 


Example 7~8 shows coding of the TYPE clause. NUM-DATE-ITEM is declared to be 
of type NUMERIC-DATE, and is formatted using the ASERIESNATIVE convention. 
LONG-DATE-ITEM has data formatted according to the convention and language . 
‘determined by the system hierarchy. LONG-TIME-ITEM is declared to be of type 
LONG-TIME, and is formatted using the UNITEDKINGDOM1 convention and the 


ENGLISH language. 

81 NUM-DATE-ITEM PIC X(8) TYPE IS NUMERIC-DATE 
‘USING CONVENTION OF "“ASERIESNATIVE". 

81 LONG-DATE-ITEM PIC X(2@) TYPE IS LONG-DATE. 

@1 LONG-TIME-ITEM PIC X(2@) TYPE IS LONG-TIME 
USING CONVENTION OF "UNITEDKINGDOM1" 

LANGUAGE OF "ENGLISH". 
Example 7-8. Coding the TYPE Clause 
USAGE Clause 


The USAGE clause specifies the format of a data item. . 


If the USAGE clause is specified at a group level, it applies to each elementary item in 
the group. 


The USAGE clause can appear in any data-description entry with a level-number other 
than 66 or 88. (This is a Unisys extension. ee 


If the USAGE clause is written in the data-description entry for a group item, it can also 
be written in the data-description entry for any subordinate elementary item of the 
group item, but the same USAGE clause must be specified by both entries. Items with 
different USAGE clauses can appear in the same record. (This is a Unisys extension.) 
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The general format of this clause is as follows: 


BINARY [ TRUNCATED | 
COMPUTATIONAL 
COMP 

CMP 
CONTROL-POINT 
cP 

DISPLAY 

DOUBLE 

EVENT 

INDEX 

KANJI 

LOCK > 

REAL 

TASK 


[ USAGE IS ] 


Explanation of Format 


BINARY (Unisys Extension) 


The USAGE IS BINARY clause indicates that data is in a binary-coded format. A binary 
item is capable of representing a value to be used in computations and therefore is 
always numeric. 


Binary items occupy memory as follows: 


‘e When the declared size is less than or equal to 11 decimal digits, the actual size is 
equal to 1 computer word; however, the item is not necessarily aligned on a word 
boundary. (This size is equivalent to 6 DISPLAY digits or 12 COMPUTATIONAL 
digits.) 

e When the declared size is greater than 11 digits, the actual size is equal to 2 
computer words (the equivalent of 12 DISPLAY digits); however, the item is not 
necessarily aligned on a word boundary. 


e The size of the record is determined by the actual size of the item (1 or 2 computer 
words). 


Note: In some cases, the compiler issues a warning because an elementary 
item declared at 01-level with USAGE IS BINARY is treated as if the 
TRUNCATED phrase had been specified for the item. In a future 
release, this inconsistency will be eliminated. 


Although BINARY items are not required to start at a word boundary, faster execution 
results when these items start at a word boundary. 


7-42 a 8600 0296-000 


DATA DIVISION 


BINARY TRUNCATED (Unisys Extension) 


If the TRUNCATED phrase is specified for an item, the contents of the PICTURE clause 
are used for high-order digit truncation, and when the item is used as a destination, for 
size-error determination. 


If the TRUNCATED phrase is not specified for an item, no truncation of high-order 
digits occurs, and when the item is used as a destination, size-error determination is 
limited to arithmetic faults such as integer-overflow conditions. 


COMPUTATIONAL, CMP, or COMP 
CMP and COMP are abbreviations for COMPUTATIONAL. 


Elementary COMPUTATIONAL data items are represented internally as contiguous 
4-bit digits. 


A COMPUTATIONAL item can represent a value to be used in computations and must 
be numeric. A numeric literal is a character string with characters selected from the 
digits "0" through "9", the plus sign (+), the minus sign (-), and the decimal point. Digits 
"A" through "F" are NOT numeric. COMPUTATIONAL fields on the A Series oe are 
packed-decimal numeric items, not hexadecimal strings. 


If a group item is described as COMPUTATIONAL, the elementary items in the group 
are COMPUTATIONAL. The group itself is not COMPUTATIONAL and cannot be used 
in computations. 


CONTROL-POINT, CP, or TASK 


The USAGE IS CONTROL-POINT clause is a synonym for USAGE IS TASK. CP is an 
abbreviation for CONTROL-POINT. 


If a group item is described with the USAGE IS TASK clause, the elementary items in 
the group are all task items. The group itself is not a task item and cannot be used in 

. any statement except the USING phrase or within a parameter list. Elementary TASK 
items are data descriptors and, as such, occupy a single word of memory. 


An elementary TASK item can be referred to directly only in an ATTACH, CALL, 
DETACH, RUN, EXECUTE, PROCESS, CHANGE, or SET statement, or in the USING 
phrase in a task-attribute expression, or in a parameter list. Further explanation of 

. TASK items can be found in the descriptions of statements that reference them and i in 
the task-attribute descriptions. 


_ When a data usage is declared as TASK, the item can be a 77-level or a 01-level item ¢ or 
can be subordinate to a 01- level item declared with USAGE IS TASK. 


Task items cannot be doubly subscripted. That is, a task item with an OCCURS clause 
cannot have a subordinate task item with an OCCURS clause. Task items cannot be 

_redefined by items of any other usage. No other clauses are allowed on an item with ~ 
USAGE IS TASK. 
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DISPLAY 


DISPLAY data items are depicted internally as contiguous 8-bit characters represented 
in the EBCDIC character set. . 


The group item is considered to be a group data item that has an alphanumeric class, 
USAGE IS DISPLAY, and can be referenced at any place in the syntax acceptable for 
such an item. The size of the group item is in terms of DISPLAY characters aligned 
according to the rules for the DISPLAY phrase. The rule is that one character exists for 
every two 4-bit digits that form a part of the group item. (This is a Unisys extension.) 


The USAGE IS DISPLAY clause indicates that data is in a standard data format. 


If the USAGE clause is not specified for an elementary item or for any group to which 
the item belongs, the usage is implicitly DISPLAY. 


Every occurrence of a DISPLAY data item begins and ends on a byte boundary. Ina 
record description, the declaration of a DISPLAY data item immediately following a 
COMPUTATIONAL or INDEX data item that does not end on a byte boundary causes 
automatic generation of a 4-bit filler between the two items. This filler area between the 
two data items is not included in the size of either item, but is included in the size of all 
group items to which the two items are subordinate. Similarly, if the last item declared 
in a group item at the next-lowest hierarchic level isa COMPUTATIONAL or an INDEX 
data item that does not end on a byte boundary, automatic generation of a 4-bit filler 
occurs. This filler is included in the size of the group item. 


The PICTURE and USAGE clauses are the only clauses valid when the TYPE clause is _ 


specified. When the USAGE clause is used with the TYPE clause, the usage must be 
DISPLAY. (This paragraph is a Unisys extension.) 


DOUBLE or REAL 

The USAGE IS REAL and USAGE IS DOUBLE clauses indicate that data is in an 
internal floating-point format. A REAL or DOUBLE item is capable of representing a 
value to be used in computations and is always numeric. Neither the PICTURE clause 
nor the SIGN clause are permitted for REAL or DOUBLE items. 

REAL and DOUBLE items occupy memory as follows: 


e AREAL item is single precision; the actual size is equal to 1 computer word. 
e ADOUBLE item is double precision; the actual size is equal to 2 computer words. 
e Both REAL and DOUBLE items are not necessarily word-aligned. 


Although REAL or DOUBLE items are not required to start at a word boundary, faster 
execution results when these items do start at a word boundary. 


EVENT 


Items described with the USAGE IS EVENT clause are used as a common interlock 
between two or more processes, thus providing an efficient means of correlating the 
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activities of one process with its related processes. Elementary EVENT items occupy 2 
words of memory. For information and syntax for controlling and testing event-names, 
refer to the CAUSE, RESET, IK, and WAIT statements. 


EVENT usage is allowed only on a 77-level or a 01-level item; if used on a 01-level item, 
a subordinate OCCURS clause is allowed. No other entries are permitted with an 
event-name. EVENT items cannot be redefined by items of any other type. 


INDEX 


An INDEX data item (an elementary item described with the USAGE IS INDEX clause) 
contains a value that must correspond to the occurrence number of a table element. The 
elementary item cannot be a conditional variable. If a group item is described with the 
USAGE IS INDEX clause, the elementary items in the group are all index data items. 
The group itself is not an index data item and cannot be used in the SEARCH or the 
SET statement, or in a relation condition. 


An index data item can be referenced explicitly only in a SEARCH or a SET statement, a 
relation condition, the USING phrase of a PROCEDURE DIVISION header, or the 
USING phrase of a CALL statement. 


A group item is also considered to be a group data item if its class is numeric, if it has 
index usage, and if it can be referenced at any place in the syntax that is acceptable for 
such an item. The size of the group item is considered in terms of DISPLAY characters 
(4 characters for each subordinate index data item). 


An index data item can be part of a group that is referenced in a MOVE or I/O 
statement; in this case, no conversion takes place. 


An index data item can contain a signed value. An index data item occupies the same 
space and has the same alignment as an item declared PICTURE S9(7) USAGE IS 
COMPUTATIONAL. 


The SYNCHRONIZED, JUSTIFIED, PICTURE, VALUE, and BLANK WHEN ZERO 
clauses cannot be used to describe group or elementary items declared with the USAGE 
IS INDEX clause. 


KANJI (Unisys Extension) 


Kanji data items are depicted internally as contiguous 16-bit characters represented in 
the Japanese Kanji character set. Each Kanji character consists of 16 bits and occupies 2 
bytes of memory. 


When the Kanji phrase is specified for a group item, it implies that all subordinate 
elementary items are declared as USAGE IS KANJI. Any Kanji group item is regarded 
as an alphanumeric item whose frame size is 8 bits (DISPLAY), except when a Kanji 
group item is compared with a figurative constant and when a figurative constant is 
moved to a Kanji group item. Ifa usage is specified for a data item that is subordinate to 
the group item, the usage for both items must be identical. An item with a KANJI clause 
contains Kanji items. 
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All Kanji data items belong to the class alphanumeric, and the Kanji category is 
subdivided into Kanji and Kanji-edited. 


Kanji usage is a type of double-octet usage. 


LOCK 


The same rules apply to declaring data usage as ocr as those declaring data usage as 
EVENT. 


For information and syntax for controlling and testing LOCK items, refer to the LOCK 
and UNLOCK statements in Section 9, “PROCEDURE DIVISION Statements.” 


Elementary LOCK items occupy 2 words of memory. 


This item does not affect the use of.the data item, although the specifications for some 
statements in the PROCEDURE DIVISION can restrict the USAGE clause of the 

reference operands. The USAGE clause can affect the radix or type of character 
representation of the item. 


See Also 


e For information on using the CAUSE statement to initiate communication between 
processes in an asynchronous processing environment, refer to “CAUSE (Unisys 
extension)” in Section 9, “PROCEDURE DIVISION Statements.” 


e For information about evaluating conditions, refer to “IF” in Section 9, 
“PROCEDURE DIVISION Statements.” 


e For information on using the LOCK statement to deny related processes access 
to acommon storage area, refer to “LOCK (Unisys extension)” in Section 9, 
“PROCEDURE DIVISION Statements.” 


e For information on using the RESET statement to control communication between 
processes in an asynchronous processing environment, refer to “RESET (Unisys 
Extension)” in Section 9, “PROCEDURE DIVISION Statements.” 


e For information on using the UNLOCK statement to unlock a previously locked 
common storage area, refer to “UNLOCK (Unisys Extension)” in Section 9, 
“PROCEDURE DIVISION Statements.” 


e For information on using the WAIT statement to suspend program execution for a 
specified time or until one or more conditions are TRUE, refer to “WAIT (Unisys 
_ Extension)” in Section 9, “PROCEDURE DIVISION Statements.” 


VALUE Clause 
The VALUE clause defines the value of constants, the value of REPORT SECTION 
printable items, the initial value of WORKING-STORAGE items, the initial value of 
_ data items in the COMMUNICATION SECTION, and the values associated with a 
condition-name. 


The VALUE clause cannot be stated for any items of variable size. 
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The VALUE clause cannot be used with the GLOBAL or OWN clause. 


The VALUE clause has the following formats: 
Format Explanation 


1 Specifies the value of constants, the initial value of WORKING-STORAGE 
items, the value of REPORT SECTION printable items, and the initial 
value data of items in the COMMUNICATION SECTION. 


2 Permits alternative, overlapping groupings of elementary items. 
3 Specifies values associated with a condition-name. 


Format 1 


The general format of this clause is as follows: 


7a 


VA } IS literal 


Explanation of Format 1 


VALUE or VA 


VA is an abbreviation for VALUE. (This is a Unisys extension.) 


literal 


A signed numeric literal must have a signed numeric PICTURE character string 
associated with it. . 


A numeric literal must have a value in the range of values indicated by the PICTURE 
clause and must not have a value that requires truncation of nonzero digits. A 
nonnumeric literal must not exceed the size indicated by the PICTURE clause. 

A figurative constant can be substituted for the literal. 


The VALUE clause must not conflict with the category of the data item as described in 
the PICTURE clause. Table 7-4 shows the rules that apply. 
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Table 7-4. VALUE Clause Rules by Data Category 


Data Category Rules 


‘Numeric The literal must be numeric. If the literal defines the value of 
a WORKING-STORAGE item, the literal is aligned in the data 
item according to the standard rules for data alignment. 


Alphabetic, alphanumeric, The literal must be a nonnumeric literal. The literal is 
alphanumeric- edited, or aligned in the data item as if the data item were described 


numeric-edited as alphanumeric. Editing characters in the PICTURE clause 
are included in determining the size of the data item but 
have no effect on initialization of the data item., Therefore, 
the VALUE clause for an edited item is presented in an 
edited form. 


Kanji or Kanji-edited The literal clause must be a Kanji literal. If the VALUE 
Clause is specified for an edited item, no edit operation 
- occurs. 


The VALUE clause must not conflict with other clauses in the data description of the 
item or in the data description within the hierarchy of the item. The following rules 


apply: 


e Initialization occurs independently of the BLANK WHEN ZERO and the 
| JUSTIFIED clause. 


e The VALUE clause must not be stated in a data-description entry that contains 
an OCCURS clause or in an entry that is subordinate to an entry containing an 
OCCURS clause. This rule does not apply to condition-name entries. 


e The VALUE clause must not be stated in a data-description entry that contains 
a REDEFINES clause or in an entry that is subordinate to an entry containing a 
REDEFINES clause. This rule does not apply to condition-name entries. 


e Ifthe VALUE clause is used in an entry at the group level, the literal must bea — 

. figurative constant or a nonnumeric literal, and the group area is initialized without 
consideration for the individual elementary or group items contained within this 
group. The VALUE clause cannot be stated at the subordinate levels within this 
group. 

e The VALUE clause must not be written for a group containing items for which 
USAGE (other than USAGE IS DISPLAY) is explicitly or implicitly specified. 
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Table 7-5 shows the rules that govern the use of the VALUE clause in each section of 
the DATA DIVISION. 


Table 7-5. VALUE Clause Rules by Section 


Section Rules 


FILE . The VALUE clause can be used only in condition-name 
entries. 


WORKING-STORAGE and . The VALUE clause must be used in condition-name entries. 


COMMUNICATION ; Zi aa 
The VALUE clause can also be used to specify the initial 


value of any other data item; in this case, the clause causes 
the item to assume the specified value at the start of the 
object program. lf the VALUE clause is not used in the 
description of an item, the initial value is undefined. 


LINKAGE The VALUE clause can be used only in condition-name 
entries. 


REPORT _ If the elementary report entry containing the VALUE clause 
does not contain a GROUP INDICATE clause, then the 
printable item assumes the specified value each time the 
report group is printed. However, when the GROUP 
INDICATE clause is included, the specified value is presented 
only when certain execution-time conditions are met. 


In bound procedures, the VALUE clause cannot be used for any item declared explicitly 
in the data declaration, or declared implicitly by using the GLOBAL or OWN compiler 
control options. . 


See Also 


-e For information on determining the category of a data item, refer to “PICTURE 
Clause” earlier in this section. 


e For information on condition-names, refer to “Data-Description Entry for 
Condition-Names” later in this section. 
Data-Description Entry for Renaming Entries 


Format 2 of the data-description entry uses the RENAMES clause. The RENAMES 
clause permits alternative, possibly overlapping, groupings of elementary items. 


One or more RENAMES clauses can be written for a logical record. 


All RENAMES clauses that refer to data items in a given logical record must immediately 
follow the last data-description entry of the associated record-description entry. 
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Format 2: Renaming Entries 


THROUGH 
THRU | 


66 data-name-1; RENAMES data-name-2 | { 


} data-name-S ; 


Note: Level-number 66, data-name-1, and the semicolon (;) are shown in the 
preceding format for clarity. Level-number 66 and data-name-1 are 
not part of the RENAMES clause. 


Explanation of Format 2 


Data-name-1 cannot be used as a qualifier and can be qualified only by the names of the 
associated 01-level, field description (FD), communication description (CD), and sort 
merge description (SD). Neither data-name-2 nor data-name-3 can have an OCCURS 
clause in the data-description.entry or be subordinate to an item that has an OCCURS 
clause in the data-description entry. 


Data-name-2 and data-name-3 must be names of elementary items or groups of 
elementary items in the logical record and cannot be the same data-name. A 66-level 
entry cannot rename another 66-level entry, nor can it rename a 77-, 88-, or 01-level 
entry. 


The beginning of the area described by data-name-3 must not be to the left of the 
beginning of the area described by data-name-2. The end of the area described by 
data-name-3 must be to the right of the end of the area described by data-name-2. 
Data-name-3, therefore, cannot be subordinate to data-name-2. 


Data-name-2 and data-name-3 can be qualified. 
The words THRU and THROUGH are equivalent. 


None of the items in the range, including data-name-2 and data-name-3 (if specified), can 
be an item of variable size as defined in the OCCURS clause. 


When data-name-3 is specified, data-name-1 is a group item that 

e Includes all elementary items starting with data-name-2 if data-name-2 is an 
elementary item 

e Includes the first elementary item in data-name-2 if data-name-2 is a group item 

e Concludes with data-name-3 if data-name-3 is an elementary item 

e Concludes with the last elementary item in data-name-3 if data-name-3 is a group 
item 


When data-name-3 is specified and data-name-2 is an elementary COMPUTATIONAL 
or INDEX data item, data-name-3 must be positioned to begin at an 8-bit character 
boundary. (This is a Unisys extension.) . 
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When data-name-3 is specified and is an elementary COMPUTATIONAL or INDEX data 
item, data-name-3 must be positioned to end at the end of an 8-bit character boundary. 
(This is a Unisys extension.) 


When data-name-3 is not specified, data-name-2 can be either a group or an elementary 
item. When data-name-2 is a group item, data-name-1 is treated as a group item; | 
when data-name-2 is an elementary item, data-name-1 is treated as an elementary 
item. Data-name-1 assumes all characteristics of data-name-2 as determined from the 
data description of data-name-2, including usage, justification, synchronization, editing 
requirements, and so forth. 


Data-Description Entry for Condition-Names 


Format 3 of the data-description entry assigns values to condition-names. A 
condition-name is a name assigned to a specific value, a set of values or a range of values 
within a complete set of values that a data item can assume. The data item itself is 
called a conditional variable. The general format of the data-description entry for a 
condition-name is as follows: _ 


Format 3: Condition-Names 


VALUE IS 
VAIS 
VALUES ARE 
VA ARE 


P THROUGH} ,. 
|: literal-3 a } literal | ae 


literal-1 ca 


88 condition-name; THRU 


} literal-2 | 


Explanation of Format 3 


_ Each condition-name requires a separate entry with level-number 88. Format 3 contains 
the name of the condition and the value, values, or range of values associated with the 
condition-name. The condition-name entries for a particular conditional variable must 
follow the entry describing the item with which the condition-name is associated. 


A condition-name can be associated with any data-description entry that contains a 
level-number except the following: . 

e Another condition-name. 

e A level-66 item. 


e Agroup item containing items for which USAGE (other than USAGE IS DISPLAY) 
is explicitly or implicitly specified. (This is a Unisys extension.) 


e An index data item. 
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In a condition-name entry, the VALUE clause is required. The VALUE clause and the 
condition-name itself are the only two clauses permitted in the entry. The characteristics 
of a condition-name are implicitly those of the conditional variable. 


Wherever the THROUGH phrase is used, literal-1 must be less than literal-2, literal-3 
less than literal-4, and so forth. 


The words THROUGH and THRU are equivalent. 


Example 


Example 7-9 shows the coding of condition-names. THIS-YEAR is the conditional 
variable, and the months JANUARY through DECEMBER are the condition-names. 
If JUNE has the assigned value 6, the following entry could be written using the 
condition-name JUNE: 


IF JUNE PERFORM ... 


This coding is logically equivalent to using the conditional variable THIS-YEAR and 
writing: 


IF THIS-YEAR IS EQUAL TO 1991 PERFORM ... 
The coding condition-names for this example are shown in Example 7-9. 


G1 THIS-YEAR PIC 9999. 
88 JANUARY VALUE 1 
88 FEBRUARY VALUE 2 
88 MARCH VALUE 3 
88 APRIL VALUE 4. 
88 MAY VALUE 5. 
88 JUNE VALUE 6. 
88 JULY VALUE 7. 
88 AUGUST VALUE 8 
88 SEPTEMBER VALUE 9. 
88 OCTOBER VALUE 19. 
88 NOVEMBER VALUE 11. 
88 DECEMBER VALUE 12. 
88 SPRING VALUE 3 THRU 5. 
88 THIRTY DAYS VALUE 9, 4, 6, 11. 


Example 7-9. Coding Condition-Names 


See Also 
e Refer to “VALUE Clause” earlier in this section for the details on this clause. 


e Refer to “Condition-Name Condition” in Section 8, “PROCEDURE DIVISION 
Concepts,” for information on this simple relation condition. 
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'WORKING-STORAGE SECTION 


The WORKING-STORAGE SECTION is composed of the section header followed by 
data-description entries for noncontiguous data items, record-description entries, or both 
entries. Each WORKING-STORAGE SECTION record-name and noncontiguous item 
name must be unique because these names cannot be qualified. Subordinate data-names 
need not be unique if they can be made unique by qualification. 


Noncontiguous WORKING-STORAGE Items 


Items and constants in the WORKING-STORAGE SECTION have no hierarchic 
relationship to one another need not be grouped into records, provided that they do not 
need:to be further subdivided. Instead, these items and constants are classified and 
defined as noncontiguous elementary items. Each of these items is defined in a separate 
data-description entry, beginning with the special level-number 77. | 


The general format of this section is as follows: 


171 data-name { 


PICTURE ; 
USAGE IS INDEX 


[ Any other data-description clauses | . 


WORKING-STORAGE Records 


Data elements and constants in the WORKING-STORAGE SECTION that bear a 
definite hierarchic relationship to one another must be grouped into records according to 
the rules for formation of record descriptions. All clauses used in record descriptions in © 
the FILE SECTION can be used in record descriptions in the WORKING-STORAGE 
SECTION. 
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Example | 
Example 7-10 shows the coding of the WORKING-STORAGE SECTION. 


WORKING-STORAGE SECTION 


77 MASTER-KEY PIC 9(8) COMP. 
77 TOTAL-SALES | PIC 9(10) COMP. VALUE ZEROS. 
@1 -STATE-TABLE. 
@3 STATES. 
@5 CALIF PIC 9(5). 
@5 MICH | PIC 9(5). 
@5 FLORIDA PIC 9(5). 
@5 ARIZONA PIC 9(5). 
@3 STATE-KEY REDEFINES STATES OCCURS 4 TIMES. 
@5 STATE-CODE PIC 99. 
@5 COUNTY PIC 99. 


@5 CAPITAL-CODE PIC 99. 
@1 HEADING-LINE. 


03 FILLER PIC X(52) VALUE SPACES. 
@3 FILLER PIC X(17) VALUE 

"SALES PERFORMANCES". 
@3 FILLER PIC X(1@) VALUE SPACES. 
83 PAGE-NO . PIC 9999. 
03 FILLER PIC X(49) VALUE SPACES. 


Example 7-10. Coding the WORKING-STORAGE SECTION 


LOCAL-STORAGE SECTION (Unisys Extension) 


The optional LOCAL-STORAGE SECTION describes parameters to be received, 
allowing separate tasks or procedures to be bound from another program. These 
parameters are described with USE EXTERNAL statements. 


The general format of items in this section is as follows: 


LD local-storage-name. | Any data description clauses | . 


Explanation of Format 


The local-storage-description (LD) entry is followed by item a ae used in the 
WORKING-STORAGE SECTION. 


Local-storage items are associated with a specific procedure by being listed in the WITH 

clause of the USE statement for the procedure. All local-storage-names must be unique. 
An LD entry is required for each procedure that receives data as parameters. That is, a 

USING clause is present in both the invocation of the procedure and the USE statement 
in the section header. 
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See Also 


Refer to the Binder Reference Manual for program samples that show binding. 
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PROCEDURE DIVISION Concepts 


The fourth and last division of a source program, the PROCEDURE DIVISION, must 
be included in every COBOL source program. This division can contain declarative and 
nondeclarative procedures. 


PROCEDURE DIVISION Header 


The PROCEDURE DIVISION is identified by, and must begin with, the following 
format: - a 


data-name 
file-name 
PROCEDURE DIVISION | USING <¢ task-name 


event-name 
lock-name 


Explanation of Format 


The optional USING clause names the identifiers received as parameters in a tasking, 
bound procedure, library, or Inter-Program Communication (IPC) environment. | 


When the USING clause is present, the object program operates as if each identifier in 
the list were replaced by the corresponding identifier from the USING clause of the 
CALL, PROCESS, or RUN statement of the calling program. | 


A data-name, file-name, task-name, event-name, or lock-name in the USING clause of 
the PROCEDURE DIVISION header must be defined in the LINKAGE SECTION of 
the program in which this header occurs, and must have a 01 or 77 level-number and 
must not be a redefined item. 


When the RECEIVED BY REFERENCE clause appears in a data description for an 
identifier, the corresponding identifier refers to a single set of data available to both the 
calling and the called program. 


When the data-name is RECEIVED BY CONTENT, the invocation of the procedure 
initializes the corresponding data-name in the USING clause of the called program to the 
current value in the initiating program. The correspondence is by position and not by 
symbolic name. Only the tasking and bound-procedure environments support by value 
parameters. . 
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See Also . 
_¢ For information about the USING clause with IPC, refer to “PROCEDURE 


DIVISION in the IPC Module” in Section 13, “ANSI Inter-Program Communication 
(IPC).” 


e For a description of the USING clause with libraries, refer to Section 15, “Libraries.” 


PROCEDURE DIVISION Body 


The body of the PROCEDURE DIVISION must conform to one of the following two 
formats: 


Format 1 


DECLARATIVES. 
section-name SECTION [ segment-number | . declarative-sentence. 
[ paragraph-name. [ sentence ] .. | Sant os 
END DECLARATIVES . 


section-name SECTION [segment-number] . 
[ paragraph-name. [ sentence ] oe gan 


Format 2 


{ paragraph-name. [ sentence ]...} ... 


Explanation of Format 1 and Format 2 


DECLARATIVES SECTIONS must be grouped at the beginning of the PROCEDURE 
DIVISION and must be preceded by the keyword DECLARATIVES and followed by the 
keywords END DECLARATIVES. 


A section consists of a section header followed by one or more successive perenne: A 
section ends as follows: 

e Immediately before the next section 

e At the end of the PROCEDURE DIVISION 


e At the keywords END DECLARATIVES in the DECLARATIVES SECTION of the 
PROCEDURE DIVISION 
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A procedure is composed of a paragraph, a group of successive paragraphs, a section, or a 
group of successive sections in the PROCEDURE DIVISION. If one paragraph is in a 
section, then all paragraphs must be in sections. A procedure-name is a word used to 
refer to a paragraph or a section in the source program in which the name occurs. The 
procedure-name consists of a paragraph-name (which can be qualified) or a section-name. 


A paragraph consists of a paragraph-name followed by a period and by one or more 
successive sentences. A paragraph ends as follows: 


e Immediately before the next paragraph-name or section-name 
e At the end of the PROCEDURE DIVISION 


e At the keywords END DECLARATIVES in the DECLARATIVES SECTION of the 
PROCEDURE DIVISION 


A sentence consists of one or more statements and ends in a period. 


A statement is a syntactically valid combination of words and symbols beginning with a 
COBOL74 verb. 


The end of the PROCEDURE DIVISION and the physical end of the program is the 
physical position ina COBOL source program after which no further procedures appear. 


Example > 
Example 8-1 is a sample program that illustrates the use of declaratives. 
IDENTIFICATION DIVISION. 


ENVIRONMENT DIVISION. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 
SELECT INPUT-FILE ASSIGN TO DISK 
FILE STATUS IS INPUT-STATUS. 


DATA DIVISION. 
FILE SECTION. 
FD INPUT-FILE 
VALUE OF TITLE IS "DISK-FILE". 
G1 INPUT-REC PIC X(8Q). 


WORKING-STORAGE SECTION. 
77 INPUT-STATUS PIC XX. 


PROCEDURE DIVISION. 
DECLARATIVES. 
DECL-1 SECTION. 
USE AFTER STANDARD ERROR PROCEDURE ON INPUT. 
D-9919. 
DISPLAY "I/O ERROR READING FILE". 


Example 8-1. Use of Declaratives 
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DISPLAY "FILE STATUS IS " INPUT-STATUS. 
STOP RUN. . 
END DECLARATIVES. 


MAIL~1808 SECTION. 

P-1919. 
MOVE "@8" TO INPUT-STATUS. 
OPEN INPUT INPUT-FILE. 
READ INPUT-FILE. 
STOP RUN. 


Example 8-1. Use of Declaratives (cont.) 


Categories of Statements and Sentences 


Statements and sentences can be of the following three types: 


e Conditional 
e Compiler-directing imperative 


e Program-directing imperative 


Conditional Statements and Sentences 


A conditional statement contains a condition that can be TRUE or FALSE, and specifies 
actions to be taken that depend on the truth value of the condition. The program 
performs a test to determine the value of the condition and performs a specified action 
when the condition is TRUE and another specified action when the condition is FALSE. . 
For example, the IF condition THEN imperative-statement statement directs the 
program to perform the THEN statement when the specified condition is TRUE. 


A conditional sentence can contain several imperative statements associated with a 
condition. A conditional sentence must end with a period. 


- The conditional statements are listed in Table 8-8 at the end of this section. 
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Compiler-Directing Imperative Statements and Sentences 


A compiler-directing imperative statement causes the compiler to take a specific action 
during the compilation process. The compiler-directing imperative statements include 
the following statements: 


e The COPY statement, which directs the compiler to incorporate text from a library 
program into the program that contains the COPY statement 

e The USE statement, which 
- Specifies procedures to be used for I/O exception handling 


- Identifies a separately compiled program to be used as a task or to be bound into 
the COBOL74 host program 


— Specifies a declarative as an interrupt procedure 


A compiler-directing sentence is a single compiler-directing statement ending in a period. 


Program-Directing Imperative Statements and Sentences 
A program-directing imperative statement causes the program to take a specific 
unconditional action. An imperative statement can consist of a sequence of imperative 


statements. 


The program-directing imperative statements are listed in Table 8-8 at the end of this 
section. 


When the user-defined word imperative-statement appears ina general format notation, 
it refers to one of the following: | 


e Asequence of consecutive imperative sentences ended by a period 
e An ELSE phrase associated with a previous IF statement 
e A WHEN phrase associated with a previous SEARCH statement 


An imperative sentence is an imperative statement ending in a period. 
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Arithmetic Expressions 


An arithmetic expression can be one of the following: 


e Anidentifier of a numeric elementary item 

e Anumeric literal | 

e Anumeric function or an extended function with a numeric result 
e Identifiers and literals separated by arithmetic operators 

e Two arithmetic expressions separated by an arithmetic operator 


e Anarithmetic expression enclosed in parentheses 
Any arithmetic expression can be preceded by a unary operator. 


Identifiers and literals appearing in an arithmetic expression must represent either 
numeric elementary items or numeric literals on which arithmetic can be performed. 


In a conditional expression, the use of a simple variable in parentheses, particularly when 
that simple variable is subscripted, can have undesirable results. Unisys recommends 
that you avoid this type of coding. 

Arithmetic ee 


Five binary and two unary arithmetic operators can be used in arithmetic expressions 
and are listed in Tables 8-1 and 8-2. . 


Table 8-1.. Binary Arithmetic Operators 


Symbol Meaning 


+ (plus sign) . Addition 


— (minus sign) Subtraction 
* (asterisk) Multiplication 
/ (slash) Division 


we . Exponentiation 


Table 8-2. Unary Arithmetic Operators 


Symbol! Meaning . 


+ (plus sign) The effect of multiplication by +1 


— (minus sign) The effect of multiplication by —1 
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_ Formation and Evaluation Rules 


Parentheses in arithmetic expressions define the order in which elements are evaluated. 
Expressions in parentheses are evaluated first; in nested parentheses, evaluation . 
proceeds from the least inclusive set. When parentheses are not used, or when 
parenthesized expressions are at the same level of inclusiveness, the following order of 
procedure is implied: ; 


1. Unary operation 

2. Exponentiation 

3. Multiplication and division 
4 


Addition and subtraction 


Parentheses either eliminate ambiguities in logic where consecutive operations of 
the same procedure appear or modify the normal hierarchic sequence of execution 
in expressions where deviation from the normal precedence is necessary. When 
the sequence of execution is not specified by parentheses, the execution order for 
consecutive operations of the same procedure is from left to right. 


An arithmetic expression can begin only with a left parenthesis, a plus sign (+), a minus 
sign (-) , or a variable. A one-to-one correspondence must be maintained between left 
and right parentheses of an arithmetic expression so that each left parenthesis is to the 
left of its corresponding right parenthesis. . 


The COBOL operator for exponentiation (**) causes any operand less than 12 digits 
long to be converted to double-precision representation before the operation. The 
exponentiation is performed on the double-precision operands. The result is truncated 
to single precision for any receiving field that is less than 12 digits long. 


The valid combinations of operators, variables, and parentheses that can be arranged 
in an arithmetic expression are summarized in Table 8-3. If a combination is shown as 
not valid, it means that the symbols cannot occur next to each other in an arithmetic 
expression. 


Table 8-3. Combination of Symbols in Arithmetic Expressions 


First Symbol Second Symbol 


- Identifier or - Unary +or | 
Literal e/eF A + - 


* ee 4 Pe N P 


Unary + or - P N N 
Legend . continued 


P Combination of symbols is permitted. 
N Combination of symbols is not valid. 
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Table 8-3. Combination of Symbols in Arithmetic Expressions (cont.) 


First Symbol Second Symbol 


Identifier or Unary + or 
Literal 


P 
N 


Legend 
P Combination of symbols is permitted. 


N | Combination of symbols is not valid. 
Numeric Functions 


A numeric function can be specified as a sending operand in an arithmetic statement, a 
MOVE statement, or an arithmetic expression. 


The functions described in the following text are Unisys extensions. An extended 
function can be specified as an arithmetic expression in the COMPUTE statement. 


Refer to Volume 2 for information about the FORM-KEY function. 


DIV 


The DIV function is an integer division function that returns an integer equal to the 
integer part of the quotient after division. 


The format for the DIV function is as follows: 


FUNCTION DIV (argument-1, argument-2) 


Explanation of Format 


Argument-1 represents the dividend, and argument-2 the divisor. Argument-1 and 
argument-2 can be any language-defined arithmetic expression, including a valid function 
call that returns a numeric value. The result returned can be a real or an integer value, 
depending on the argument type. The result of argument-2 must not be 0 (zero). 
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Example 


In the three COMPUTE statements in Example 8-2, the DIV function returns the 
integers 5, 3, and 30, respectively. 


COMPUTE A = FUNCTION DIV(19,2). 


COMPUTE A = FUNCTION DIV(19,3). 


COMPUTE A = FUNCTION DIV(19,.33). . 
Example 8-2. Coding the DIV Function 


FORMATTED-SIZE 


The FORMATTED-SIZE function returns as a value the formatted size of the 
data-name. The returned value is equal to the following: 


Length of the data-name in bytes + 
(number of Kanji data items subordinate to the data-name * 2) 


The format for the FORMATTED-SIZE function is as follows: 


FUNCTION FORMATTED-SIZE (data-name) 


Explanation of Format 

The number of Kanji data items subordinate to the data-name is determined according 
to the same rules that are used for record formatting in the WRITE DELIMITED 
statement. 


The data-name can be qualified. It cannot be subscripted or indexed, nor can the 
data-name be a RENAMES entry. , 


The data-name must be either a group item or any category of elementary item 
described implicitly or explicitly as USAGE IS DISPLAY or USAGE IS KANJI. 


Example 

Example 8-3 shows the results returned by the FORMATTED-SIZE function. 
080206 IDENTIFICATION DIVISION. 

@8930G ENVIRONMENT DIVISION. 


BBB4BS DATA DIVISION. 
@@G5GGB WORKING-STORAGE SECTION. 


Example 8-3. Results of FORMATTED-SIZE Function 
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O@0690 77. THE-SIZE PIC 9(8). 

9087008 81 ACCOUNT-FILE-RECORD. 

GOB82O @3 ACCT-NO PIC 9(8). 

BOB9IBOG 83 NUMBER-OF-DETAILS PIC 99. 

GB190B9 G3 TRANSACTION-DETAILS OCCURS 1 TO 196 

681190 DEPENDING ON NUMBER-OF-DETAILS. 

981280* The physical size of TRANSACTION-DETAILS is 138 bytes. 
981320* The formatted size of the same group item is 142 
8G1490* bytes because of the leading and trailing delimiters 
@615@8* accounted for around each Kanji elementary item. 


801620 @5 DETAIL-IDENT PIC 9(8). 

Q61700 . 85 DETAIL-TEXT PIC X(28) KANJI. 
981800 05 DETAIL-AMOUNT PIC S$9(8)V99. 

891960 @5 DETAIL-DESCRIPTION PIC X(49) KANJI. 


982988 PROCEDURE DIVISION. 

902188 ONLY-HEADER. 

982288 MOVE 1 TO NUMBER-OF-DETAILS. 

@02300* Function FORMATTED-SIZE (account-file-record) should now 
Q02490* return a value of 152: 18+ (1 * (138 + (2 * 2))) 
9G258B COMPUTE THE-SIZE = 

992608 FUNCTION FORMATTED-SIZE (ACCOUNT-FILE-RECORD) . 
0G279D DISPLAY THE-SIZE. 

QG28GG* “Function FORMATTED-SIZE (account-file-record) should now 
Q22980* return a value of 2859: 18 + (20 * (138 + (2 * 2))) 
O83000 MOVE 28 TO NUMBER-OF-DETAILS. 

9931908 COMPUTE THE-SIZE = 

983206 FUNCTION FORMATTED-SIZE (ACCOUNT-FILE-RECORD). 
993322 DISPLAY THE-SIZE. 

983488 STOP RUN. 


Example 8-3. Results of FORMATTED-SIZE Function (cont.) 


See Also 
For information about the WRITE DELIMITED statement, refer to “WRITE” in 
Section 9, “PROCEDURE DIVISION Statements.” 


MOD 


The MOD function returns the modulus value of argument-1 divided by argument-2. 
The modulus value is equal to the following: 


argument-1 - [argument-2 * INTEGER(argument-1/argument-2) ] 
The INTEGER function, implicit in the MOD function, is defined as the largest integer 


less than or equal to the argument. For example, INTEGER(+ 1.5) returns 1, and 
' INTEGER(-1.5) returns —2. 
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The format for the MOD function is as follows: 


FUNCTION MOD (argument-1, argument-2) 


Explanation of Format 


The arguments must be integer literals or data-names of type numeric. The scale should 
be equal to 0 (zero). No numbers can follow the character V in the character string 
declaration. The specifications follow the CODASYL proposal for the MOD function. 
Argument-2 must not be 0 (zero). 


Example 


Example 8-4 shows four COMPUTE statements that use the MOD function and shows 
their results. The accompanying calculations show how each result was obtained. 


COMPUTE A 


FUNCTION MOD(1@,3). 
1 

COMPUTE A = FUNCTION MOD(11,-5). 

11 - ( -5 * FUNCTION INTEGER (11 / -5) ) 
11 - ( -5 * FUNCTION INTEGER (-2.2) ) 

11 - (-5 * -3) 

11] - 15 = -4 


COMPUTE A = FUNCTION MOD (-11,5). 

| -11 - (5 * FUNCTION INTEGER (-11 / 5) ) 
-11 - (5 * FUNCTION INTEGER (-2.2) ) 
wll -(5* -3)- 

-11 +15 =4 


COMPUTE A = FUNCTION MOD(19,0.33) . 

18 - ( 9.33 * FUNCTION INTEGER (19 / 8.33) ) 

18 - ( 6.33 * FUNCTION INTEGER (30.303030...) ) 
19 - ( 9.33 * 30) 


19 - 9.9 = G.1 
Example 8-4. Coding the MOD Function 
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OFFSET 


The OFFSET function returns a value equal to the number of characters that precede 
data-name in the logical record in which data-name is defined. 


The format for the OFFSET function is as follows:. 


OFFSET (data-name) 


Explanation:of Format 


If data-name refers to a packed numeric data item that is not aligned on a character 
boundary, then the returned value is equal to the number of characters preceding the - 
character with which data-name begins. If data-name is a record-name or a 77-level 
item, the value returned is 0. Data-name can be qualified. 


Example | 

In Example 8-5, if Y is a 05-level data item within a 01-level group, the COMPUTE 
statement returns a value to Z that is the sum of the number of characters of ca fields 
preceding Y in the same 01-level group data structure. 


COMPUTE Z = OFFSET (Y). 
Example 8-5. Coding the OFFSET Function - 


REM 


The REM function returns as a value the remainder of a division. 


The format for the REM function is as follows: 


FUNCTION REM ( argument-1, argument-2 ) 


Explanation of Format 


Argument-1 represents the dividend, and argument-2 the divisor. Argument-1 and 
argument-2 can be any language-defined arithmetic expression, including a valid function 
call that returns a numeric value. The result returned can be either a real or an integer 
value depending on the argument type. The result of argument-2 must not be 0 (zero). 
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Example 


In Example 8-6, the four uses of the REM function return the values 1, 1, -1, and 0.1, 


respectively. 
COMPUTE A = FUNCTION REM(19,3). 
COMPUTE A = FUNCTION REM(11,-5). 
COMPUTE A= FUNCTION REM(-11,5). 
COMPUTE A = FUNCTION REM(19,9.33). 


Example 8-6. Coding the REM Function 


Multiple Function Calls in an Expression 


Example 8-7 shows the way in which functions can be combined ina COMPUTE 
statement to form an arithmetic expression. 


QG8200* The first example shows that the values returned by 
@00300* the DIV and REM functions are used in an addition operation. 


G0B419* 

@GG58G COMPUTE A = FUNCTION DIV(19,2) + FUNCTION REM(19,3). 
BOD6BO ~=5+1=6 

980618* 


9G0700* In the next example, X and Y are numeric variables: 

9GG820 COMPUTE A = 16 + FUNCTION DIV(10,X + Y). 

928819* . . 
Q0B908* In the next example, values returned by DIV and REM functions 
962180* are used as the arguments for a DIV function: 


@8B195* 

@@G118 COMPUTE A = FUNCTION MOD(-11,5) + 

888120 FUNCTION DIV((FUNCTION REM(10,3) *18) , 
908130 FUNCTION DIV(10,FUNCTION DIV(19,3) ) ). 
800140 = 4 + 

908158 FUNCTION DIV(FUNCTION REM(19,3) * 19, 
968168 FUNCTION DIV(18,3) ) 

890178 = 4 + FUNCTION DIV( (1 * 18) ,3) 

989189 = 4 + FUNCTION DIV( (1 * 18) ,3) 

808198 =4+3 

802008 =7 


Example 8-7. Coding Multiple Function Calls in an Expression 


Conditional Expressions 


Conditional expressions identify conditions that are tested so that the object program 
' ean choose between paths of control that depend on the truth value of the condition. 
Conditional expressions are specified in I; PERFORM, and SEARCH statements. The 
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two categories of conditions associated with conditional expressions are simple conditions 
and complex conditions. Each can be enclosed in any number of paired parentheses; the 
paired parentheses do not change the category of the condition. _ 


Simple Conditions 


Simple conditions are relation, class, condition-name, sign, and event-identifier 
conditions. A simple condition has a truth value of TRUE or FALSE. The inclusion of 
parentheses in simple conditions does not change the simple truth value, 


There is a permanent restriction on the use of parentheses in relational conditions. This | 
restriction is not always enforced by a syntax error. Violating the following rule can 
result in an unexpected program failure or an incorrect program execution. 


Parentheses in conditional expressions in COBOL74 should not be used to surround 
simple variables, particularly when the simple variables are subscripted. 


Example 


Example 8-8 shows correct and incorrect uses of parentheses. In the following code the 
first two statements are legitimate, but the third statement should be avoided. 


IF A (I) IS EQUAL TO B (J) ... 
IF (A (I) IS EQUAL TO B (J)) ... 
IF (A (I)) IS EQUAL TO (B (J)) ... 


In the following code, the first line is technically correct, but it is better represented by 
the second or third line of code. 


IF (C) IS EQUAL TO (D) 
IF C IS EQUAL TO D 
IF (C IS EQUAL TO D) 


In the following code, the first line is technically correct, but it is better represented by 
the second or third line of code. 


IF (LITERAL-1) IS EQUAL TO (LITERAL-2) 
IF LITERAL-1 IS EQUAL TO LITERAL-2 
IF (LITERAL-1 IS EQUAL TO LITERAL-2) 


Example 8-8. Parentheses Restrictions in Simple Conditions 


| | Relation Condition 


8-14 


A relation condition causes a comparison of two operands that can be data items 
referenced by an identifier, literals, or values resulting from an arithmetic expression. A 
relation condition has a truth value of TRUE if the relation exists between the operands. 
Comparison of two numeric operands is permitted regardless of their respective USAGE 
clauses. However, for all other comparisons, the operands must have the same usage. If 
either of the operands is a group item, the nonnumeric comparison rules apply. 
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The general format of a relation condition is as follows: 


> 


LESS THAN } 
< 


18 [wor] { EQUALTO | 


1s [Nor] { 


identifier-1 . 
literal-1 | IS [ 


ey 


NOT | { 
arithmetic-expression-1 


identifier-2 
: literal-2 


arithmetic-expression-2 


Note: The required relational characters >, <, and = are not underlined 
to avoid confusion with other symbols, such as the symbol for 
“greater than or equal to.” 


Explanation of Format | 


The first operand (identifier-1, literal-1, or arithmetic-expression-1) is called the subject 
of the condition; the second operand (identifier-2, literal-2, or arithmetic-expression-2) is 
called the object of the condition. 


The relational operator specifies the type of comparison to be made inarelation _ 
condition. When used, NOT and the next keyword or relational character form one 
relational operator that defines the comparison to be executed for a truth value. For 
example, NOT EQUAL is a truth test for an unequal comparison, and NOT GREATER 
is a truth’test for an equal or less than comparison. Table 8-4 shows the meanings of the 
relational operators. 


Table 8-4. Meanings of Relational Operators 


| Operator . Meaning 


IS [ NOT ] GREATER THAN Greater than or not greater than 
IS [ NOT] > 


IS [ NOT ] LESS THAN Less than or not less than 
IST NOT] < 


IS [ NOT ] EQUAL TO Equal to or not equal to 
IS[ NOT] = 
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Comparing Numeric Operands 


For numeric operands, a comparison is made with respect to the algebraic value of the 
operands. The length of the literal or the arithmetic expression operands, in terms 

of number of digits represented, is not significant. Zero is considered a unique value 
regardless of the sign. 


A comparison of these operands is permitted regardless of the manner in which the 
usage is described. Unsigned numeric operands are considered positive for purposes of 
comparison. 


Comparing Nonnumeric Operands 


For nonnumeric operands, or for one numeric and one nonnumeric operand, a 
comparison is made with respect to a specified collating sequence of characters. If one of 
the operands is specified as numeric, it must be an integer data item or an integer literal 
and the following conditions apply: 


e Ifthe nonnumeric operand is an elementary data item or a nonnumeric literal, the 
numeric operand is treated as if it were moved to an elementary alphanumeric 
data item of the same size as the numeric data item (in terms of standard data 
format characters). The numeric operand is then treated as if the contents of this 
alphanumeric data item were compared with the nonnumeric operand. 


e Ifthe nonnumeric operand is a group item, the numeric operand is treated as if it 
were moved to a group item of the same size as the numeric data item (in terms of 
standard data format characters). The numeric operand is then treated as if the 
contents of this group item were compared with the nonnumeric operand. 


e Anoninteger numeric operand cannot be compared to a nonnumeric operand. 


e Ifone of the operands is an undigit literal, then it cannot be compared to a numeric 
operand. Otherwise, it is treated as if it were moved to an elementary alphanumeric 
data item of the appropriate length. Each pair of hexadecimal digits represents one 
8-bit character. (This is a Unisys extension.) 


The size of an operand is the total number of standard data-format characters in the 


operand. Numeric and nonnumeric operands can be compared only when the usage is 
the same. 
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Operands of equal size and operands of unequal size are described as follows: 


e Ifthe operands are of equal size, comparison effectively proceeds by comparing 
characters in corresponding character positions, starting from the high-order end 
and continuing until either a pair of unequal characters is encountered or the 
low-order end of the operand is reached. The operands are determined to be equal if 
all pairs of characters compare equally through the last pair, when the low-order end 
of the operand is reached. 


The first pair of unequal characters encountered is compared to determine their 
relative position in the collating sequence. The operand that contains the character 
positioned higher in the collating sequence is considered to be the greater operand. 


e Ifthe operands are of unequal size, comparison proceeds as if the shorter operand 
were extended on the right by sufficient spaces to make the operands of equal size. 


See Also 
e For a detailed description of move operations, refer to “MOVE” in Section 9, 
“PROCEDURE DIVISION Statements.” © 


e For information about the collating sequence, refer to “OBJECT-COMPUTER” in 
Section 5, “ENVIRONMENT DIVISION.” 


e For information on the character P refer to “PICTURE Clause” in Section 7, “DATA 
DIVISION.” 


Comparing Kanji Operands 
For Kanji operands, the relational operators are restricted to the following: 


IS [NOT] EQUAL TO 
IS [NOT] = 


If the operands are of unequal size, the right side of the shorter operand is filled with 
Kanji space characters to make both operands of equal size before the comparison is 
made. ; 


Comparing Index-Names and Index Data Items 
Relation tests can be made between the following: 
e Two index-names. The result is the same as if the corresponding occurrence 


numbers were compared. 


e An index-name and a data item (other than an index data item) or literal. The 
occurrence number that corresponds to the value of the index-name is compared to 
the data item or literal. 


e An index data item and an index-name or another index data item. The actual 
values are compared without conversion. 
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Any result of the comparison between an index data item and a data item or a literal that 
is not specified in the preceding list is not allowed. 


Class Condition 


_ identifier IS [ NOT ] { 


8-18 


The class condition determines whether the operand is NUMERIC or ALPHABETIC. 
For example, you might want to use the class condition test to ensure that an item that is 
supposed to contain numeric data actually does contain numeric digits. You can code an 
IF statement to test for a class condition. The following is an example: 


IF NEW-NUM IS NUMERIC 
PERFORM CALC-ROUTINE 
ELSE PERFORM ERROR-ROUTINE. 


When the NUMERIC option is specified, the class condition tests whether the operand 
consists entirely of only the characters 0 through 9, with or without the operational sign. 


When the ALPHABETIC option is specified, the class condition tests whether the 
characters are contained entirely in the alphabetic truthset. For most application 
programs, the alphabetic truthset includes the characters A through Z and the space. 
For programs using ‘the internationalization features, the alphabetic truthset can be 
specified with respect to the system collating sequence. (The internationalization 
features are a Unisys extension.) 


The general format of the class condition is as follows: 


NUMERIC 
ALPHABETIC 


Explanation of Format 


The usage of the operand ina NUMERIC test must be DISPLAY or i 
COMPUTATIONAL. (Allowing COMPUTATIONAL items in the class condition is 
a Unisys extension.) The usage of the operand in an ALPHABETIC test must be 
DISPLAY. 


When used, NOT and the next keyword specify a class condition that defines the class 
condition test to be executed for a truth value; for example, NOT NUMERIC is a truth 
test for determining that an operand is nonnumeric. 


The NUMERIC test cannot be used with an item described as alphabetic in its data 
description or with an item described as a group item composed of elementary items with 
one or more operational signs. 


If the data description of the item being tested does not indicate the presence of an 


operational sign, the item being tested is determined to be numeric only if the contents 
are numeric and an operational sign is not present. If the data description of the item 
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indicates the presence of an operational sign, the item being tested is determined to be 
numeric only if the contents are numeric and a valid operational sign is present. 


The ALPHABETIC test cannot be used with an item described as numeric in its data 
description. For most applications, the item being tested is determined to be alphabetic 
only if the contents consist of any combination of the alphabetic characters A through 

Z and the space. For applications using the internationalization features, the data 

item being tested is determined to be alphabetic only if the contents consist of any 
combination of the alphabetic characters in the truthset. To use a system collating 
sequence other than the characters A through Z and the space, the program must use 
the alphabet-name IS CCSVERSION phrase of the SPECIAL-NAMES paragraph. (The 
internationalization features are a Unisys extension.) 


- See Also © 


e The position and representation of valid operational signs are discussed under 
“PICTURE Clause” and “SIGN Clause” in Section 7, “DATA DIVISION.” 


e Refer to Section 16, “Internationalization,” for information about truthsets. 


Condition-Name Condition 


In a condition-name condition, a conditional variable is tested to determine whether or 
not its value is equal to one of the values associated with a condition-name. The general 
format of the condition-name condition is as follows: 


condition-name 


Explanation of Format 

If the condition-name is associated with a range or ranges of values, then the conditional 
variable is tested to determine whether its value falls in this range, which includes the 
end values. 


The rules for comparing a conditional variable with a condition-name value are the same 
as those specified for relation conditions. 


The result of the test is TRUE if one of the values corresponding to the condition-name 
equals the value of its associated conditional variable. 


Sign Condition 


The sign condition determines whether or not the algebraic value of an arithmetic _ 
expression is ss than, greater than, or equal to 0. 
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The general format of the sign condition is as follows: 


POSITIVE 
arithmetic-expression IS | NOT | {NEcaTive 


ZERO 


Explanation of Format 


When used, NOT and the next keyword specify a sign condition that defines the 
algebraic test to be executed for a truth value; for example, NOT ZERO is a truth test 
for a nonzero (positive or negative) value. An operand is positive if its value is greater 
than 0, negative if its value is less than 0, and 0 if its value is equal to 0. The arithmetic 
expression must contain at least one reference to a variable. 


Event-Identifier Condition 


In the event-identifier condition, an event variable, an event-valued file attribute, or an | 
event-valued task attribute is tested to determine whether the condition is TRUE or 
FALSE. 


The general format of the event-identifier condition is as follows: 


event-identifier 


Explanation of Format 


The use of an event-identifier as a condition returns the value TRUE when the event has 
been caused and not reset. The event-identifier condition returns the value FALSE if 
the event is reset. 


Complex Conditions 


8-20 


A complex condition is formed by combining simple conditions, combined conditions, 
and/or complex conditions with logical connectors (logical operators AND and OR) or by 
negating these conditions with a logical negator (the logical operator NOT). The truth 
value of a complex condition, whether parenthesized or not, is the truth value that 
results from the interaction of all the stated logical operators on the individual truth 
values of simple conditions or on the intermediate truth values of conditions logically 
connected or logically negated. - 
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Table 8-5 shows the logical operators and explains their meanings. 


Table 8-5. Logical Operators and Their Meaning | 


Logical Operator Explanation | 3 


Logical conjunction. The truth value is TRUE if both of the conjoined 
conditions are true, and the truth value is FALSE if at least one of the 
conjoined conditions is FALSE. 


Logical inclusive OR. The truth value is TRUE if at least one of the 
included conditions is TRUE, and the truth value is FALSE if both 
included conditions are FALSE. 


Logical negation or reversal of the truth value. The truth value is TRUE if 
the condition is FALSE, and the truth value is FALSE if the condition is 
TRUE. . 


Negated Simple Conditions 
A simple condition is negated by using the logical operator NOT. 


The general format of a negated simple condition is as follows: 


- NOT simple-condition 


Explanation of Format 


The negated simple condition has a truth value opposite of the truth value for a simple 
condition. Thus, the truth value of a negated simple condition is TRUE if the truth value 
of the simple condition is FALSE; the truth value of a negated simple condition is FALSE 
only if the truth value of the simple condition is TRUE. Enclosing a negated simple 
condition in parentheses does not change the truth value. 


Combined and Negated Combined Conditions | 


A combined condition results from connecting conditions with one of the logical operators 
AND or OR. The general format of a combined condition is as follows: 


condition { } condition { 


OR OR \ eonsition | a 
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A condition can be any of the following: 


e Asimple condition — 
e Anegated simple condition 
e Acombined condition 
-0@ A negated-combined condition 
e Acombination of the preceding conditions 


The negated-combined condition is created if the NOT logical operator is followed by a 
combined condition enclosed in parentheses. 


A combination of the preceding conditions must be specified according to the rules 
summarized in Table 8-6. 


Although parentheses need never be used when either AND or OR is used exclusively in 
a combined condition, parentheses can be used to establish the precedence of operators © 
when a mixture of the logical operators AND, OR, and NOT is used. 


Table 8-6 shows the ways in which conditions and logical operators can be combined 
and parentheses used. A one-to-one correspondence must exist between left and 
right parentheses so that each left parenthesis is to the left of its corresponding right 
parenthesis. 


Table 8-6. Combinations of Conditions, Logical Operators, and Parentheses 


Left-to-Right Element Sequence 


First in Last in 
~ Condi- - Condi- 
tional tional If Element not lf Element not 
Expres- Expres- first, must be _ fast, must be 
Base Element sion sion preceded by: followed by: 


Simple-condition ~ OR, NOT, AND , ( | OR, AND, ) 


OR or AND simple-condition, simple-condition, 
) NOT, ( 


OR, AND, ( simple-condition, 
( 


OR, NOT, AND, ( simple-condition, 
NOT, ( 


simple-condition, OR, AND, ) 
) 


Thus, the element pair OR NOT is permissible, but the pair NOT OR is not permissible. 
NOT is permissible, but NOT NOT is not permissible. 


8-22 | | 8600 0296-000 


\ 


PROCEDURE DIVISION Concepts 


Abbreviated Combined Relation Conditions 
Combined relation conditions can be abbreviated when one of the following occurs: 


e The sequence has no parentheses, and a succeeding relation condition with a subject 
is the same as the preceding relation condition. 


e The sequence has no parentheses, and a succeeding relation condition with a subject 
and a relational operator is the same as the preceding relation condition. 


One of the following abbreviations can be used for any relation condition except the first: 


e Omit the subject of the relation condition. 


e Omit the subject and relational operator of the relation condition. 


The format of an abbreviated combined relation condition is as follows: 


: is AND 
relation-condition { { OR 


} [ NOT ] [ relational-operator | object } ah 


Explanation of Format 


In a sequence of relation conditions, both of the previously mentioned forms of 
abbreviation can be used. Using such abbreviations has the same effect as inserting the 
last stated subject in place of the omitted subject, and the last stated relational operator 
in place of the omitted relational operator. The result of such an implied insertion must 
comply with the rules listed in Table 8-6. The insertion of an omitted subject, an omitted 
relational operator, or both ends when a complete simple condition is encountered within 
a complex condition. 


The interpretation applied to the use of the word NOT in an abbreviated combined 
relation condition is as follows: 


e Ifthe word or symbol immediately following NOT is GREATER, >, LESS, <, 
EQUAL, or =, then NOT is part of the relational operator. 


e Inany other situation, NOT is interpreted as a logical operator, causing the implied 
insertion of a subject or a relational operator to result in a negated relation 
condition. 
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Example 


Table 8-7 contains some examples of abbreviated combined relation conditions and their 
expanded equivalents. 


Table 8-7. Abbreviated Combined Relation Conditions and Their Expanded 


Equivalents 
Abbreviated Combined Relation Condition Expanded Equivalent 
a >bANDNOT <cORd ; ((a > b) AND (a NOT < c)) 


OR (a NOT < d) 
a NOT EQUAL b OR c (a NOT EQUAL b) OR (a NOT EQUAL c) 
NOTa =bORc (NOT (a = b)) OR (a = c) 

NOT (a GREATER b OR < c) NOT ((a GREATER b) OR (a < c)) 
NOT (a NOT > b AND c AND NOT d) NOT (((a NOT > b) AND (a NOT > c)) 
AND (NOT (a NOT > d))) 


Condition Evaluation Rules 
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Parentheses can be used to define the order of evaluation for individual conditions of 
complex conditions when the implied evaluation precedence does not apply. Conditions 
in parentheses are evaluated first, and within nested parentheses, evaluation proceeds 
from the least inclusive condition to the most inclusive condition. When parentheses are 
not used, or parenthesized conditions are at the same level of inclusiveness, the following 
hierarchical order of logical evaluation is used until the final truth value is determined: 

Values are established for arithmetic expressions. 
2. Truth values for simple conditions are established in the following order: 

a. Relation (following the expansion of any abbreviated relation condition) 

b. Class 

c. Condition-name 

d. Switch-status 

e. Sign 

Truth values for negated simple conditions are established. 


4, Truth values for combined conditions are established: AND logical operators 
followed by OR logical operators. 


5. Truth values for negated combined conditions are established. 


If the sequence of evaluation is not completely specified by parentheses, then 
consecutive operations of the same hierarchical level are evaluated from left to right. 


8600 0296-000 


PROCEDURE DIVISION Concepts 


See Also 


For information on the order in which elements of an expression are evaluated, refer to 
“Formation and Evaluation Rules” earlier in this section. 


Common Phrases in Statements 


The ROUNDED phrase, the SIZE ERROR phrase, and the CORRESPONDING phrase 
can be used in a number of statements. Because the rules for these phrases are similar 
for each of the statements in which they are used, these phrases are explained only once. 
If there are unique aspects in the use of a phrase in a statement, the aspect is described 
in this section. 


In the following paragraphs, a resultant identifier is the identifier associated with a 
result of an arithmetic operation. 


ROUNDED Phrase 


Truncation occurs if, after decimal point alignment, the number of places in the 
fractional portion of the result of an arithmetic operation is greater than the number of 
places provided for the fraction in the resultant identifier. The truncation occurs relative 
to the size provided for the resultant identifier in its PICTURE clause. 


When rounding is requested, the absolute value of the resultant identifier is increased 
by adding the number 1 to its low-order digit whenever the absolute value of the next 
least-significant digit of the intermediate data item is greater than or equal to 5. 


When the low-order integer positions in a resultant identifier are represented by the 
character P in the PICTURE clause for that resultant identifier, then rounding or 
truncation occurs relative to the rightmost integer position for which storage is allocated. 


SIZE ERROR Phrase 


The SIZE ERROR phrase enables you to specify procedures to be executed when a Size 
Error condition occurs. Size Error conditions exist under the following circumstances: 


e If, after decimal point alignment, the absolute value of a result exceeds the ea 
value that can be contained in the associated resultant identifier. 


e Division by 0 (zero) always causes a Size Error condition. If division by 0 is the cause 
of the Size Error condition, the program ends abnormally. 


The Size Error condition applies only to the final results of an arithmetic operation 
and does not apply to intermediate results, except in the DIVIDE statement. If the 
ROUNDED phrase is specified, rounding takes place before checking for Size Error 
conditions. When such a Size Error condition occurs, subsequent action depends on 
whether or not. the SIZE ERROR phrase is specified. 
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If the SIZE ERROR phrase is not specified and a Size Error condition occurs, the 
resultant value is stored in each of the receiving fields, and is left-truncated as required. 
If more than 28 significant digits are required, the program abnormally terminates with 
an error. Values of resultant identifiers for which no Size Error condition occurs are 
unaffected by size errors that occur for other resultant identifiers. 


If the SIZE ERROR phrase is specified and a Size Error condition occurs, then the values 
of resultant identifiers affected by the size errors are not altered. Values of resultant 
identifiers for which no Size Error conditions occur are unaffected by size errors that 
occur for other resultant identifiers. After the arithmetic operation is completely 
executed, the imperative statement in the SIZE ERROR phrase is executed. 


If an ADD CORRESPONDING or SUBTRACT CORRESPONDING statement produces 
a Size Error condition, the imperative statement in the SIZE ERROR phrase is not 
executed until all the individual additions and subtractions are completed. 


CORRESPONDING Phrase 


In the following description, AAA and BBB are identifiers that refer to group items. 
A pair of data items, one from AAA and one from BBB, pee a if all the following 
conditions are met: , 


e Adata item in AAA and a data item in BBB are not designated by the keyword 
FILLER, and these data items have the same data-name and the same qualifiers up 
to, but not including, AAA and BBB. 


e At least one of the data items is an elementary data item in a MOVE statement 
with the CORRESPONDING phrase. In an ADD or SUBTRACT statement with 
the CORRESPONDING phrase, both of the data items are elementary numeric data 
items. 


e The description of AAA ad BBB must not contain level-numbers 66, 77, or 88, or 
the USAGE IS INDEX clause. 


e A data item subordinate to AAA or BBB that contains a REDEFINES, RENAMES, 
OCCURS, or USAGE IS INDEX clause is ignored, as are data items subordinate 
to the data item that contains the REDEFINES, OCCURS, or USAGE IS INDEX 
clause. However, AAA and BBB can have REDEFINES or OCCURS clauses, or can 
be subordinate to data items with REDEFINES or OCCURS clauses. 


See Also 


For information about repeated data items, refer to “OCCURS Clause” in Section 7, 
“DATA DIVISION.” 
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Common Rules for Arithmetic Statements 


The arithmetic statements ADD, COMPUTE, DIVIDE, MULTIPLY, and SUBTRACT 
have the following features in common: 


e The data descriptions of the operands need not be the same; any necessary 
conversion and decimal point alignment are supplied throughout the calculation. 


e The maximum size of each operand is 23 decimal digits. (This is a Unisys extension.) 


e Each arithmetic operation is evaluated using an intermediate data item for the result 
of the operation. If the number of significant digits in the result being developed is 
greater than the number of significant digits that can be held in an intermediate data 
item, the result is truncated to the size of an intermediate data item. The contents _ 
of the intermediate data item are moved to the resultant identifier according to the - 
rules for the MOVE statement. Rounding is performed; the Size Error condition is 
determined only during this move. (This is a Unisys extension.) 


See Also 


e For details of the rules that govern move operations, refer to aoe in Section 9, 
“PROCEDURE DIVISION Statements.” 


e For information about the rounding of arithmetic result fields, refer to “ROUNDED 
Phrase” earlier in this section. 


e For information on Size Error conditions, refer to “SIZE ERROR Phrase” earlier in 
this section. 


Calculating Multiple Results with One Arithmetic Statement 


In COBOL, the ADD, COMPUTE, DIVIDE, MULTIPLY, and SUBTRACT statements 
can produce multiple results. A single statement produces results as if it were written in 
one of the following ways: 


_e Asastatement that performs all arithmetic operations necessary to arrive at the 
results and that stores the results in a temporary storage location until it is stored in 
the receiving items. 


e Asasequence of statements that combines the value of the temporary location with 
a single result. The sequence of statements is considered to be written in the same 
left-to- -right sequence in which the multiple results are listed... 


For example, the result of the statement ADD a, b,c TO c, d (c), e is equivalent to the 
following statement. Temp is an intermediate result item provided by the compiler. 


ADD a, b, c GIVING temp 
ADD temp TO c 

ADD temp TO d (c) — 

ADD temp TO e 
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Handling Incompatible Data 
When the contents of a data item referenced in the PROCEDURE DIVISION are not 


compatible with the class specified for that data item in the related PICTURE clause 
(except for the class condition), the result of such a reference is undefined. 


See Also 


For information on how to determine whether an operand is numeric or alphabetic, refer 
to “Class Condition” earlier in this section. 


Functional Grouping of COBOL74 Verbs 


Table 8-8 groups the COBOL74 verbs into categories based on their functions. Some 
verbs appear in more than one category. 


Table 8-8. Categories of COBOL74 Verbs 


Category — Function 


Arithmetic ADD Sums two or more numeric operands and 
stores the result. 


COMPUTE Assigns the value of an arithmetic 
expression to one or more data items. 


DIVIDE Divides a numeric operand into one or 
more other operands, and. stores the 
quotient and remainder. 


INSPECT Searches for and tallies the occurrences of 
(TALLYING) specified characters in a data item. 


MULTIPLY : Multiplies numeric operands and stores 
the result. 


SUBTRACT Subtracts one or the sum of two or more 
numeric operands from one or more items 
and stores the result. 


Compiler directing Incorporates text from a library program 
into a COBOL source program. 


Specifies procedures for handling 
input-output errors in addition to the 
standard procedures provided by the 
input-output control system. 


COMS interface ACCEPT MESSAGE Makes available the number of messages 
COUNT in a program application queue. 


DISABLE Closes a direct window to a station or 
disconnects a station. 


continued 
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Table 8-8. Categories of COBOL74 Verbs (cont.) 


Category . Verb Function 


Conditional 
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ENABLE 


RECEIVE 


ADD (ON SIZE 
ERROR) 


COMPUTE (ON SIZE 
ERROR) 


DELETE (INVALID 
KEY) 


DIVIDE (ON SIZE 
ERROR). 


MULTIPLY (ON SIZE 
ERROR) 


PERFORM (UNTIL) 


READ# (AT END, 
INVALID KEY) 


Opens a direct window to a station or 
checks the status of station attachment. 


Makes a message and pertinent 
information available to the program from 
a queue maintained by COMS. 


Releases a message or a message 
segment to one or more output queues 
maintained by COMS. 


Sums two or more numeric operands and 
stores the result. If a Size Error condition 
occurs, specified procedures are followed. 


Assigns the value of an arithmetic 
expression to one or more data items. Ifa 
Size Error condition occurs, specified 
procedures are followed. 


Removes a record logically from a relative 
or indexed file. If the file does not contain 
the record indicated by the key, specified 


’ procedures are followed. 


Divides a numeric operand into one or 
more other operands, and stores the 
quotient and remainder. If a Size Error 
condition occurs, specified procedures are 
followed. 


Evaluates a condition. Subsequent action 
of the object program depends on whether 
the vaiue of the condition is TRUE or 
FALSE. . 


Multiplies numeric operands and stores 
the result. If a Size Error condition occurs, 
specified procedures are followed. 


Transfers control to the specified 
subroutine until the condition in the 
UNTIL phrase is TRUE. 


For sequential access, makes available the 
next logical record from a sequential file. 
For random access, makes available a 
specific record from a mass-storage file If 
the end of the file is reached or if the file 
does not contain the indicated key, 
specified procedures are followed. 


continued 
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RETURN (AT END) 


REWRITE (INVALID 
KEY) 


SEARCH (AT END, 
WHEN) 


SORT (ON ERROR) 


START (INVALID 
KEY) 


STRING (ON 
OVERFLOW) 


SUBTRACT (ON 
SIZE ERROR) 


UNSTRING (ON 
OVERFLOW) 


Table 8-8. Categories of COBOL74 Verbs (cont.) 


Function 


Causes the next record in a sort-merge file 
to be read. If the end of the file is 
reached, specified procedures are 


| followed. 


Replaces a record logically in a 
mass-storage file. If the file does not 
contain the record identified by the 
indicated key, specified procedures are 
followed. 


Searches a table for a table element that 
satisfies a specified condition, and adjusts 
the associated index-name to indicate that 
table element. The WHEN option imposes 
conditions for the search. The AT END 
option specifies processing to be carried 
out at the end of the search operation. 


Sorts the contents of one or more input 
files. If an error condition is encountered, 
specific procedures are followed. 


Positions records logically in a relative or 
an indexed file when the file is to be read 


_ sequentially. If the file does not contain 


the indicated key, specified procedures are 
followed. 


Concatenates the partial or complete 

contents of one or more data items into a 
single data item. If an overflow condition 
exists, specified procedures are followed. 


Subtracts one or the sum of two or more 
numeric operands from one or more 
items, and stores the result. If a Size Error 
condition occurs, specified procedures are 
followed. 


Causes contiguous data items in a sending 
field to be separated and placed into 
multiple receiving fields. if the value of 
the pointer is less than 1 or greater than 
the sending field, or if all the receiving 
fields have been acted upon and the 
sending field contains characters that 
have not been examined, specified 
procedures are followed. 


continued 
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Table 8-8. Categories of COBOL74 Verbs (cont.) 


Category Function 


Data movement 


DMSH interface 


WRITE (INVALID 
KEY, END-OF-PAGE) 


ACCEPT (DATE, DAY, 
TIME, TIMER, 
TODAYS-DATE, 
TODAYS-NAME) 


INSPECT 
(REPLACING) 
MOVE 


STRING 


UNSTRING 


ABORT- 
TRANSACTION 


ASSIGN 


BEGIN- 
TRANSACTION 


CANCEL- 


_ TRANSACTION 


POINT 
CLOSE 


~ COMPUTE 


CREATE 


DELETE 
DMSTATUS 


DMTERMINATE 


Releases a logical record for an output or 
an input-output file. If the file does not 
contain the indicated key, or if an 
End-Of-Page condition exists, specified 
procedures are followed. 


Makes low-volume data available to a 
specified data item. Data from the DATE, 
DAY, TIME, TIMER, TODAYS-DATE, or 
TODAYS-NAME register is moved to the 
specified item. 


‘Searches for and replaces occurrences of 


specified characters in a data item. 


Transfers data, according to the rules of 
editing, to one or more data areas. 


Concatenates the partial or complete 
contents of one or more data items into a 
single data item. 


Causes contiguous data items in a sending 
field to be separated and placed into 
multiple receiving fields. 


Discards updates made in a transaction 
after a BEGIN-TRANSACTION statement. 


Assigns the value pointed to by the current 
record from one data set to another. 


Places a program in transaction state. 


Discards updates in a transaction to an 
intermediate point or to the beginning of 
the transaction. 


Closes a database. 


_ Assigns a value to a Boolean item in the 


current record of a data set. 


Initializes the user work area of a data set 
record. 


Finds, locks, and deletes a record. 


Indicates whether an exception has 
occurred and identifies the exception. 


Terminates the program. 


continued 
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Category 


Imperative 


END-TRANSACTION 
FIND 


FREE 
GENERATE 


IF 
INSERT 
LOCK 


MODIFY 
OPEN 


RECREATE 
REMOVE 


SAVE-TRANSACTION: 


POINT 
SECURE 


SET 


STORE 


ACCEPT 


ADD (without ON 
SIZE) 

ALLOW 

ALTER 

ATTACH 


CALL 


Table 8-8. Categories of COBOL74 Verbs (cont.) 


Function 
Takes a program out of transaction state. 


Transfers a record to the work area 
associated with a data set or global data. 


Unlocks the current record. 

Creates. a subset in one operation. 
Tests an item for null value. 

Places a record in a manual subset. 


Finds a record and locks it against 
concurrent modification. 


Synonymous with the LOCK verb. 


Opens a database and designates the 
access mode. 


Partially initializes the user work area. 


Finds and locks a record, and removes it 


from the subset. 


Provides an intermediate point in an audit 
transaction. 


Enables other programs to read a record 
but not update that record. 


Alters the current path or changes the 
value of an item in the current record. 


Places a new or modified record in a data 
set. 


Makes low-volume data available to a 
specified data item from an operator 
display terminal (ODT). 


Sums two or more numeric operands and 
stores the result. 


Executes an interrupt procedure that has 
been attached to an EVENT item. 


Modifies the destination of a labeled G 
TO statement. 


Associates an interrupt procedure with an 


_ EVENT item. 


Transfers control to a separate task or 
procedure. 


continued | 
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Category 
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CHANGE 
CLOSE 


COMPUTE (without 
ON SIZE ERROR) 


CONTINUE 
DELETE (without 
INVALID KEY) 
DETACH 


DISALLOW 


DISPLAY 


DIVIDE (without ON 
SIZE ERROR) - 


EXECUTE 
EXIT 


EXIT PROCEDURE 
EXIT PROGRAM 


GO TO 


INSPECT 
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Table 8-8. Categories of COBOL74 Verbs (cont.) 


Function 


Is used in communication between 
processes in an asynchronous processing 
environment to initiate specified events. 


Modifies a file or a task attribute. 


Ends the processing of a file, a reel or a 
unit of a file. Also specifies the disposition 
of the file and of the device to which the 
file is assigned. 


Assigns the value of an arithmetic 
expression to one or more data items. 


Passes control to a previously called and 
exited synchronous process. 


Removes a record logically from a relative 
or indexed file. 


Dissociates a procedure from a task item. 
or an EVENT item. 


Prevents execution of an interrupt 
procedure that has been attached to an 
event. 


Causes low-volume data to be transferred 
to an ODT. 


Divides a numeric operand into one or 
more other operands, and stores the 
quotient and remainder. 


Is synonymous with the RUN verb. 


Indicates a logical end for a series of 
sections or paragraphs referenced by a | 
PERFORM statement. 


Returns control from a bound procedure. 


Returns control from a dependent task to 
the program that initiated it. 


Transfers control unconditionally from one 
procedure to another. Control is not 
implicitly returned to the statement 
following the GO statement. 


Searches for and tallies or replaces 
specified characters in a data item. 


continued 
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Table 8-8. Categories of COBOL74 Verbs (cont.) 


Category Function 


MOVE 


MULTIPLY (without 
ON SIZE ERROR) 


OPEN 
PERFORM 


PROCESS 


READ (without AT 
END or INVALID 
KEY) . 


~ RELEASE 


RETURN 


REWRITE (without 
INVALID KEY) 


RUN 


Enables a process to deny related 
processes access to a common storage 
area or to test a common storage area for 
a locked condition. 


Merges two or more identically sequenced 
files on a set of specified keys. The 
merged records then become available to 
an output procedure or an output file. 


Transfers data, according to the rules of 
editing, to one or more receiving data 
items. 


Multiplies numeric operands and stores 
the result. 


Makes a file available for processing. 


Transfers control unconditionally to one 
procedure or a group of consecutive 
procedures, and returns control to the 
statement following the PERFORM 
statement. 


Initiates the parallel execution of another 
task. 


For sequential access, makes available the 
next logical record from a sequential file. 
For random access, makes available a 
specific record from a mass-storage file. 


Transfers records to the initial phase of a 


- sort operation, and writes records to a sort 


file. 


Causes a specified event to be turned off 
in an asynchronous processing 
environment. 


Obtains sorted records from a sort 
operation or merged records from a merge 
operation. 


Replaces a record logically in a 
mass-storage file. 


Initiates another program as an 
independent, asynchronous task. 


continued 
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Table 8-8. Categories of COBOL74 Verbs (cont.) 


Category Function 


SEARCH (without AT Searches a table for a table element that 

END or WHEN) Satisfies a specified condition, and adjusts 
the associated index-name to indicate that 
table element. 


Repositions a mass-storage file to a 
specified record. 


Establishes reference points for 
table-handling operations by setting 
indexes associated with table elements. 
Also can alter the value of external 
Switches and conditional variables. 


Sequences the records in a file on a set of 
specified keys, and makes the sorted 
records available to output procedures or 
output files. 


START (without Positions records logically in a relative or 
INVALID KEY) an indexed file when the file is to be read 
sequentially. 


STOP Suspends the execution of a program 
either permanently or temporarily. 


STRING (without ON Concatenates the partial or complete 
OVERFLOW) contents of one or more data items into a 
single data item. 


SUBTRACT (without Subtracts one or the sum of two or more 
SIZE ERROR) numeric operands from one or more 
items, and stores the results. 


UNLOCK - Unlocks a common storage area so that 
related processes can access it. 


UNSTRING (without Causes contiguous data items in a sending 
ON OVERFLOW) field to be separated and placed into 
multiple receiving fields. 


USE Specifies procedures for I/O exception 
handling. 


WAIT Suspends program execution for a 
specified period of time. 


WRITE (without ON Releases a logical record for an output or 
OVERFLOW) an input-output file. 


Input-Output ACCEPT (identifier) Transfers low-volume data from an ODT to 
a specified data item. 


continued 
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Category 


Inter-Program 


Communication 


AWAIT-OPEN 


DELETE 


DISPLAY 


OPEN 
READ 


RESPOND 


REWRITE 


SEEK 


START 


STOP (literal) 


WRITE 


CALL 


CANCEL 


EXIT PROGRAM 


Table 8-8. Categories of COBOL74 Verbs (cont.) 


Function 


Causes a port file subfile to wait for a start 
dialogue request from its correspondent 
endpoint. 


Ends the processing of a file, and specifies 
the disposition of the file and of the device 
to which the file is assigned. 


Removes a logical record from a relative 
or an indexed file. 


Causes low-volume data to be transferred 
to an ODT. 


Makes a file available for processing. 


For sequential access, makes available the 
next logical record from a sequential file. 
For random access, makes available a 
specific record from a mass-storage file. 


Enables a program to accept or reject a 
request for a dialogue to be started or 
ended. 


Replaces a record logically in a 
mass-storage file. 


Repositions a file to a specified record. 


Provides a logical position for a relative or 
an indexed file when the file is to be read 
sequentially. 


Suspends the execution of a program. The 
literal is communicated to the operator, 
and execution continues with the next 
executable statement in the program. 


Releases a logical record for an output or 
an input-output file. 


Transfers contro! from one program to 
another during program execution. 


Ensures that the next time a program 
referenced in a CALL statement is called, 
the program will be in its initial state. 


Indicates the logical end of a called 
program. 


continued 
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Table 8-8. Categories of COBOL74 Verbs (cont.) 


No operation 


Ordering 


Report Writer 


Procedure branching 
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CONTINUE 


EXIT 


RELEASE 


RETURN 


SORT 


GENERATE 


INITIATE 
TERMINATE 


USE BEFORE 
REPORTING 


ALTER 


CALL 


EXIT 


EXIT PROGRAM 


GO 


Function 


Indicates that no executable statement is 
present. 


Indicates a logical end to a series of 
sections or paragraphs referenced by a 
PERFORM statement. 


Merges two or more identically sequenced 

_ files on a set of specified keys. The 
merged records then become available to 
an output procedure or an output file. 


Transfers records to the initial phase of a 
sort operation, and writes records to a sort 
file. 


Causes the next record in a sort-merge file 
to be read. 


Sequences a file on a set of specified keys, 
and makes the sort file available to output 
procedures or output files. 


Links the PROCEDURE DIVISION to the 
Report Writer at process time. 


Starts processing of a report. 
Terminates processing of a report. | 


| Specifies PROCEDURE DIVISION . 
statements to be executed before a report 
group is produced. 


Modifies the destination of a labeled GO 
TO statement. 


Transfers control from one program to 
another during program execution. 


indicates a logical end to a series of 
sections or paragraphs referenced by a 
PERFORM statement. 


Indicates the logical end of a called 
program. 


Transfers control unconditionally to a 


procedure-name. Control is not implicitly 
returned to the statement following the GO 
statement. 


continued 
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Category 
SDF interface 


SDF Plus interface 


SIM interface 


String handling 
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DICTIONARY 


READ FORM 
WRITE FORM — 
READ FORM 
WRITE FORM 


WRITE FORM TEXT 


DELETE 


DISCARD 
DMSTATE 


END-TRANSACTION 
INSERT 

MODIFY 

OPEN 

RETRIEVE 


SAVE-TRANSACTION 


_ POINT 


SELECT 


SET 


START INSERT 


START MODIFY 


INSPECT 
(REPLACING, 
TALLYING) 


Table 8-8. Categories of COBOL74 Verbs (cont.) 


Function 


Identifies the dictionary to be used during 
compilation. 


Reads specific and self-identifying forms. 
Writes forms from a station to a program. 
Reads a form record from a remote file. 


Writes the contents of a form record to a 


- remote file. 


Writes the contents of text arrays to a 


_ remote file. 


Deletes selected entities from the 
database 


Discards or terminates an active query. 


Returns a value that helps to identify 
errors that have occurred. 


Takes a program out of transaction state. 
Creates an entity. 

Updates existing entities. 

Opens a database. 


Retrieves the query and makes the entities 
available to the program. 


Provides an intermediate transaction 
point. 


Selects a set of entities and associates it 
with the query. 


Alters the level value expected in a 
retrieval involving a transitive closure. 


Describes the type of selection, if any, and 
associates a query name with the 
statement. 


Describes the selection and associates a 
query name with the statement. 


Searches for and tallies or replaces the 
occurrences of specified characters in a 
data item. 


continued 
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Table 8-8. Categories of COBOL74 Verbs (cont.) 


Category Function 


STRING Concatenates the partial or complete 
contents of one or more data items into a 
single data item. 


UNSTRING Causes contiguous data items in a sending 
field to be separated and placed into 
multiple receiving fields. 


Table handling SEARCH Searches a table for a table element that: 
satisfies a specified condition, and adjusts 
the associated index-name to indicate that 
table element. 


Establishes reference points for 
table-handling operations by setting 
indexes associated with table elements. 
Also alters the value of external switches 
and conditional variables. 
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Section 9 
PROCEDURE DIVISION Statements 


This section describes the PROCEDURE DIVISION statements in alphabetical order. 


ACCEPT 


The ACCEPT statement transfers low-volume data to a data item. 


The ACCEPT statement has the following three formats. 


Format Explanation 
1 “Transfers data from a hardware device to a data item 
2 Transfers data from date and time registers to a data item 
3 Transfers a formatted system date or time to a data item based on the type, 


convention, and language in effect 


Format 1 


ACCEPT identifier [ FROM mnemonic-name | 


Explanation of Format 1 
- The ACCEPT statement transfers data from the hardware device. 
If the FROM phrase is not given, the device used is the ODT. 


The mnemonic-name must also be specified in the SPECIAL-NAMES paragraph of the 
ENVIRONMENT DIVISION and must be associated with the hardware-name ODT. 


Format 2 


ACCEPT identifier FROM 


TIMER — | 
TODAYS-DATE 
TODAYS-NAME 
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Explanation of Format 2 


The ACCEPT statement transfers the value of a special register to the data item that is 
specified by the identifier, according to the rules of the MOVE statement. 


Format 3 


ACCEPT identifier | FROM ear 


DATE 
TIME 


Explanation of Format 3 


Format 3 of the ACCEPT statement transfers the formatted system date or time to the 
data item specified by the identifier using the type, convention, and language in effect for 
the item. Format 3 is used when the identifier has an associated TYPE clause. If the 
convention or language have not been declared for the item, the system determines the 

~ convention and language based on a default hierarchy. 


The FROM clause is optional and is used only for documentation. The specification of 
either DATE or TIME should match the type of the identifier. The DATE specification 
should be used when the receiving item is of type SHORT-DATE, LONG-DATE, or 
NUMERIC-DATE. The TIME specification should be used when the item is of type 
LONG-TIME or NUMERIC-TIME. If the type of the item and the special register do not 
match, the compiler issues a warning message, continues the compilation, and assumes 
the special register is valid for the type declared for the receiving item. 


General Rules 
The following information applies to all three formats. 


The incoming data is left-justified in the identifier, without consideration for editing, 
decimal point alignment, or operational sign position. Fill characters are inserted on 
the right if the size of the identifier is greater than the size of the incoming data. For 
identifiers of USAGE IS DISPLAY, the fill character is a space. For identifiers of 
USAGE IS COMPUTATIONAL, the fill character is 0 (zero). 


Any necessary conversion of data from one form of internal representation to another 
takes place during the transfer. 


See Also 


e Fora description of the contents of each special register, refer to “Special Registers” 
in Section 2, “Language Elements.” 
e For information about the TYPE clause, refer to Section 7, “DATA DIVISION.” 


e Fora discussion of the ways to localize your program, refer to Section 16, 
“Internationalization.” 
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ADD 


The ADD statement adds two or more numeric operands and stores the result. 


The ADD statement has the following three formats: 


Format Explanation 

5 The ADD...TO format stores the result of the add operation in the identifier 
following the word TO. The operands preceding the word TO are unchanged. 

2 The ADD...GIVING format stores the result of the add operation in the identifier 
following the word GIVING. The values of the operands preceding the word 
GIVING are unchanged. 

3 The ADD CORRESPONDING format adds the corresponding data items of two 
group items. 

Format 1 


D eee, eng } | 
“~~ (fiteral-1 ” Uiteral-2 _ 


TO identifier-m [ ROUNDED | [, identifier-n [ ROUNDED | | ... 


[ ; ON SIZE ERROR imperative-statement | 


Explanation of Format 1 

The values of the operands preceding the word TO are added together. The sum is 
then added to the current value of identifier-m, and the result is immediately stored in 
identifier-m. This process is repeated for each operand following the word TO. 


Each identifier must refer to an elementary numeric item. Each literal must be a 
numeric literal. 


The imperative-statement can be the NEXT SENTENCE phrase. 
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Format 2 


ADD oa verre | fee 
7 literal-1 ” [literal-2 ” Uiteral-3 oe 


GIVING identifier-m [ ROUNDED | [ , identifier-n [ ROUNDED ] ]... 


[; ON SIZE ERROR imperative-statement ] 


_ Explanation of Format 2 


The values of the operands preceding the word GIVING are added together. The sum is 
then stored as the new value of each resultant identifier: identifier-m, identifier-n, and 
so on. 


Each identifier preceding the word GIVING must refer to an elementary numeric item. 
Each identifier following the word GIVING must refer to either an elementary numeric 
item or an elementary numeric-edited item. 

Each literal must be a numeric literal. 


The imperative-statement can be the NEXT SENTENCE phrase. 


You might want to use this format when you need to retain the contents of the operands. 


_ Format 3 


ADD 


——— 


ion 


CORR } identifier-1 TO identifier-2 [ ROUNDED | 


[ ; ON SIZE ERROR imperative-statement | 


Explanation of Format 3 


Data items in identifier-1 are added to and stored in corresponding data items in 
identifier-2. 


Each identifier must refer to a group item. 


CORR is an abbreviation for CORRESPONDING. 
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The imperative-statement can be the NEXT SENTENCE phrase. 


General Rules 
The following information applies to all three formats. 


When a sending item and a receiving item in the same ADD statement share a part — but 
not all—of their storage areas, the result of the execution of the statement is undefined. 


See Also 


e Fora description of the features common to the arithmetic statements, refer 
to “Common Rules for Arithmetic Statements” in Section 8, “PROCEDURE 
DIVISION Concepts.” 


e For information on producing multiple results with one arithmetic statement, refer 
to “Calculating Multiple Results with One Arithmetic Statement” in Section 8, 
“PROCEDURE DIVISION Concepts.” 


e For information about the rounding of arithmetic result fields, refer to “ROUNDED 
Phrase” in Section 8, “PROCEDURE DIVISION Concepts.” 


e For information on Size Error conditions, refer to “SIZE ERROR Phrase” in 
Section 8, “PROCEDURE DIVISION Concepts.” 


e For information on adding group items, refer to “CORRESPONDING Phrase,” in 
Section 8, “PROCEDURE DIVISION Concepts.” 


ALLOW (Unisys Extension) — 


The ALLOW statement executes an interrupt procedure that has been attached to an 
EVENT item. 


The ALLOW statement has the following two for.nats: 


Format Explanation | 
1 Causes the specified interrupt procedures to be specifically allowed 
2 Enables you to remove the General Disallow Interrupt condition 
Format 1 


ALLOW section-name-1 Ls section-name-2 per 


Explanation of Format 1 
Execution of an ALLOW section-name statement causes the specified interrupt 


procedures (section-names) to be specifically allowed. Whenever their attached events 
are caused, they are executed unless a General Disallow Interrupt condition is in effect. 
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Section-names used in this statement must be defined in the DECLARATIVES 
SECTION with the USE AS INTERRUPT clause. 


Format 2 


ALLOW INTERRUPT 


Explanation of Format 2 


The ALLOW INTERRUPT statement is the logical opposite of the DISALLOW 
INTERRUPT statement. It removes the General Disallow Interrupt condition. 
Interrupt procedures that are queued because of the General Disallow Interrupt 
condition are executed immediately after the ALLOW INTERRUPT statement is 
executed, unless their current status is specifically disallowed. 


General Rules 
The following information applies to both formats. 


Interrupts previously disallowed by a DISALLOW section-name statement can be 
allowed by an ALLOW section-name statement during the time a General Disallow 
Interrupt condition is in effect. If the associated event is caused after an interrupt 
procedure has been specifically allowed, the interrupt procedure is queued until an 
ALLOW INTERRUPT statement removes the General Disallow Interrupt condition. 


Interrupt procedures can be successfully allowed or disallowed regardless of whether 
they are attached to an event. However, performing an ATTACH statement for any 
interrupt procedure that has not been specifically disallowed causes an Automatic 
Implicit Allow condition for that procedure. 


See Also 
e For information about associating an interrupt procedure with an EVENT item, 
refer to “ATTACH (Unisys Extension)” in this section. 


e For information about dissociating a procedure from a task item or an EVENT item, 
refer to “DETACH (Unisys Extension)” in this section. 


e For information about preventing execution of an interrupt procedure that has been . 
attached to an event, refer to “DISALLOW?” in this section. 


e For information about specifying procedures for ie) exception handling, refer to 
“USE” in this section. 
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ALTER 
The ALTER statement modifies a labeled GO TO statement. 


The general format of this statement is as follows: 


ALTER procedure-name-1 TO [| PROCEED TO | procedure-name-2 


[ , procedure-name-3 TO [ PROCEED TO | procedure-name-4 | ... 


Explanation of Format 


Execution of the ALTER statement modifies the GO TO statement in the paragraph 
named procedure-name-1, procedure-name-3, and so forth. The subsequent executions 
of the modified GO TO statements cause control to be transferred to procedure-name-2, 
procedure-name-4, and so forth. Modified GO TO statements in independent segments 
can, under some circumstances, be returned to their initial states. 


Each procedure-name-1, procedure-name-3, and so forth is the name of a paragraph that 
contains a single sentence consisting of a GO TO statement without the DEPENDING 
phrase. 


Each procedure-name-2, procedure-name-4, and so forth is the name of a paragraph or 
section in the PROCEDURE DIVISION. 


ATTACH (Unisys Extension) 


The ATTACH statement associates an interrupt procedure with an EVENT item. 


The format of the ATTACH statement is as follows: 


ATTACH section-name TO event-identifier 


Explanation of Format 


The section-name must be the name of a section in the DECLARATIVES SECTION that 
specifies the USE AS INTERRUPT clause. 


The event-identifier cannot be an event-valued file attribute. 


When an EVENT item is caused, all interrupt procedures that are then attached to | 
that event-identifier are either executed immediately (interrupting the main program) 
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or queued. If an interrupt procedure is allowed specifically, and if the General Disallow 
Interrupt condition is not in effect, the execution occurs. If an interrupt procedure is 
disallowed specifically, or if the General Disallow Interrupt condition is in effect, the 
execution is queued. 


An ATTACH statement for an interrupt procedure that has not been specifically 
disallowed causes that procedure to be implicitly and automatically allowed. Execution 
of a subsequent DISALLOW section-name statement inhibits the immediate execution 
of that interrupt procedure so that when the associated event is caused, execution is 
queued. This specific DISALLOW section-name statement remains in effect until a 
specific ALLOW section-name statement is executed, even if that section-name has 
intervening DETACH and ATTACH statements. 


Two or more interrupt procedures can be attached to a single event-identifier.. The order 
of execution of these interrupt procedures when the event is caused is the reverse of 
their order of attachment. 


A particular interrupt procedure can be attached to only one event at any one time. If 
the interrupt procedure is already attached to an event when the ATTACH statement is 
executed, the interrupt procedure is automatically detached from the old event and then 
attached to the new event. Any queued invocations of the interrupt procedure are lost. 


See Also 
e For information about executing an interrupt procedure that has been attached to an 
EVENT item, refer to “ALLOW (Unisys Extension)” in this section. 


e For information about dissociating a procedure from a task item or an EVENT item, 
refer to “DETACH (Unisys Extension)” in this section. 


e For information about preventing execution of an interrupt procedure that has been 
attached to an event, refer to “DISALLOW?” in this section. . 


e For information about specifying procedures for I/O exception handling, refer to 
“USB” in this section. 
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AWAIT-OPEN (Unisys Extension) 


The AWAIT-OPEN statement is used only for port files. This statement causes a subfile 
to wait for a start dialogue request from its correspondent endpoint. The AWAIT-OPEN 
statement does not initiate a request for a dialogue to be established. 


The general format of this statement is as follows: 


AVAILABLE 
WITH NO WAIT ? {file-name} ... 
: WITH WAIT 
AWAIT-OPEN CONNECT-TIME-LIMIT 
a 1 } 


USING integer 


Seen } 
DONT-PARTICIPATE 


Explanation of Format 
The file-name identifies one or more port files. 


The AVAILABLE phrase opens a subfile if a matching subfile has already initiated a 
request for a dialogue to be started. If no request has been sent, the AWAIT-OPEN 
statement fails and the subfile is not considered for subsequent matching. The 
AVAILABLE phrase is a way of indicating an OPEN WAIT statement with the 
AVAILABLEONLY file attribute set to TRUE. 


The NO WAIT phrase returns control to the program as soon as possible. The subfile 
waits for a request for a dialogue to be initiated while the program continues processing. 


The WAIT phrase suspends the program until an attempt to match the subfile with an _ 
incoming dialogue request either succeeds or fails. If the program specifies subfiles, the 
AWAIT-OPEN WAIT statement suspends the program until the open operation on each 
affected subfile succeeds or fails. The AWAIT-OPEN WAIT statement is the default _ 
statement and is used ifno OPEN option is specified in your program. 


The USING option enables you to use each of the USING clauses once only. 


The CONNECT-TIME-LIMIT phrase indicates the time in minutes that your program 
allows for the system to match a subfile with a dialogue request. The time in minutes is 
indicated by the value contained in identifier-1 or integer. The AWAIT-OPEN operation 
fails if a companion subfile does not initiate a dialogue request in that amount of time. If — 
you do not use the CONNECT-TIME-LIMIT phrase or if you specify a value of 0 (zero), 
your program allows an indefinite amount of time. An error results if you specify a 
negative or noninteger value. 
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Identifier-1 designates an elementary iitewer data item. Integer specifies an integer 
numeric literal. 


The PARTICIPATE phrase specifies that your program uses the RESPOND statement 
to accept or reject an offer for a dialogue to be started or ended. 


The DONT-PARTICIPATE phrase specifies that your program unconditionally accepts 
all offers to open or close a dialogue with a correspondent endpoint. 


General Rules 


You must use the RESERVE NETWORK clause in the SPECIAL-NAMES paragraph for 
the compiler to recognize AWAIT-OPEN as a reserved word. 


The ACTUAL KRY clause specifies the subfile that is awaiting an open request. If you 
do not code an ACTUAL KEY clause, the compiler assumes the number of subfilesis _ 
equal to the value of the MAXSUBFILES attribute. If you are using multiple subfiles, do 
the following: 


1. Specify the total number of subfiles in your program by using the CHANGE 
ATTRIBUTE MAXSUBFILES TO VALUE attribute-value statement. 


2. Specify the subfiles that are to await an open operation with the SELECT port-file 
ASSIGN TO PORT; ACTUAL KEY IS subfile-num clause. - 


3. Declare subfile-num and attribute-value in the WORKING-STORAGE SECTION. 


Table 9-1 shows the way the value specified in the ACTUAL KEY clause determines 
which subfile awaits an open request. 


Table 9-1. Designating Subfiles for the AWAIT-OPEN Statement 


Explanation 


O or none Every closed subfile awaits an open request. 


‘Nonzero The specified subfile awaits an open request. 


Greater than the MAXSUBFILES A run-time error occurs. 
value, or a negative number 


The system returns a value that indicates the result of an AWAIT-OPEN statement. 
You can access this value by including a SELECT file-name FILE STATUS IS 
data-name clause in your program. The operating system moves a value into the 
data-name storage area after the program performs the AWAIT-OPEN statement. You 
can then use an IF statement to test the value of the data-name and take the desired 
action, depending on the result. If you choose not to code actions for the AWAIT-OPEN 
results, the system provides a default action for each result. 


8600 0296-000 


PROCEDURE DIVISION Statements 


Table 9-2 shows the I/O status values and their meanings. 


Table 9-2. I/O Status Values for the AWAIT-OPEN Statement 


Value Explanation 


Control was returned to the program after the AWAIT-OPEN statement 
completed correctly. 


An error was detected during the execution of the AWAIT-OPEN statement. 


+t Unisys extension 


Examples 


In the following examples, it is assumed that earlier in the program the port files were 
declared by using an ACTUAL KEY clause to epecity a subfile index and that the subfile 
index was set to a particular subfile. 

Example 9-1 indicates the program is suspended until the operation fails or until the 
subport on the port file PORTFILE1 receives an incoming dialogue request that matches 
and establishes a dialogue with the corresponding endpoint. 


AWAIT-OPEN WITH WAIT PORTFILE1. 
Example 9-1. Coding an AWAIT-OPEN WITH WAIT Statement 


Example 9-2 indicates that control is returned to the program as soon as the 
AWAIT-OPEN statement is checked for semantic correctness. The subfile for port file 
PORTFILE1 awaits dialogue establishment while the program continues running. 


‘AWAIT-OPEN WITH NO WAIT PORTFILE1. 
_ Example 9-2. Coding an AWAIT-OPEN WITH NO WAIT Statement 


Example 9-3 is the same as an AWAIT-OPEN WAIT statement with the 
AVAILABLEONLY file attribute set to TRUE. When AVAILABLEONLY is TRUE, the 
AWAIT-OPEN request is matched to dialogue requests that have already been received. 
If no matching requests have been received, the AWAIT-OPEN statement fails and the 
subfile is not considered for subsequent matching. 


AWAIT-OPEN AVAILABLE PORTFILE1. 
Example 9-3. Coding an AWAIT-OPEN AVAILABLE Statement 


Example 9-4 indicates that the program waits for a request for a dialogue to be | 
established on the subfile for the port file PORTFILE2. Control is not returned 

to the program until the subfile is matched to an incoming dialogue request. The 
PARTICIPATE option indicates that the dialogue request is not automatically accepted 
when it is matched to the subfile. When the system returns control to the program, the 
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program can review and negotiate dialogue attributes, and accept or reject any offers by 
responding with the RESPOND statement. 


AWAIT-OPEN WITH WAIT PORTFILE2 USING PARTICIPATE. 
Example 9-4. Coding an AWAIT-OPEN...PARTICIPATE Statement 
Example 9-5 indicates that the program does not wait for a dialogue request to be 
established on the subfile for the port file PORTFILE3. Control is returned tothe _ 
program as soon as possible. In addition, the maximum amount of time that the system 


can wait for a successful match is equal to the value contained in the NUMER-ITEM 
item. . 


AWAIT-OPEN NO WAIT PORTFILE3 USING CONNECT-TIME-LIMIT OF NUMER-ITEM. 
Example 9-5. Coding an AWAIT-OPEN...CONNECT-TIME-LIMIT Statement 


See Also 


e For information about another type of open operation used to establish a dialogue, 
refer to “OPEN” later in this section. 


e For step-by-step information on coding port file applications, refer to the I/O 
Subsystem Programming Guide. 


e For references to file attributes, refer to the File Attributes Reference Manual. 


CALL 


The CALL statement transfers control from an object program to a separate task or 
procedure. 


The CALL statement has the following four formats: 


Format Explanation 
1 Starts an independently compiled program that is executed under the control of 
the calling program 
2 Calls a bound-procedure 
3 Starts a system dump operation 
4 Initiates an independent task by submitting a Work Flow Language (WFL) job 
See Also 


e For information on the use of the CALL statement in Inter-Program Communication 
(IPC), refer to “CALL Statement” in Section 13, “ANSI Inter-Program 
Communication (IPC).” 


e For information on the use of the CALL statement with libraries, refer to “Referring 
to a Library” in Section 15, “Libraries.” 
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Format 1 (Unisys Extension) 


CALL task-identifier WITH section-name [ USING actual-parameter-list | 


Explanation of Format 1 


Format 1 is used for calls on tasks. A task is an independently compiled program that is 
executed under the control of the calling program. 


The execution of the tasking CALL statement causes the program containing the CALL 
statement to be suspended and causes the program being called to begin execution as a 
separate task. 


Upon execution of an EXIT PROGRAM statement in the called program, the called 
program is suspended and control is returned to the next statement of the calling 
program. The calling program can call the called program again with a CONTINUE 
statement, and shared data is not reinitialized. The called program begins execution at 
its first executable statement with each CONTINUE statement. 


Execution of an EXIT PROGRAM RETURN HERE statement in the called program 

suspends the called program and returns control to the next statement of the calling 

program. Shared data is not reinitialized. A subsequent CONTINUE statement in the 

calling program returns control to the next statement after the EXIT statement in the 
- called program. . 


In the called program, execution of aSTOP RUN statement or abnormal termination 
returns control to the next statement of the calling program. Subsequent calls 
reinitialize the called program. The inclusion of a task-identifier in the USING clause 
allows a called program to make any reference to that task that is allowable in the calling 
program. 


Files to be passed as parameters must have a record description. The record described 
for the file can be passed as a parameter. In the PROCEDURE DIVISION header of 
the called program, the USING phrase must not reference any data item in the FILE 
SECTION of the called program. Either or both programs can initiate I/O to the file 
passed as a parameter in the CALL statement. . 


The name of the program to be called can either be specified at the source level in the 
SPECIAL-NAMES paragraph or be assigned from a data item at run time by moving 
or reading the title into the data item named in the USE EXTERNAL statement of 
section-name. Standard file-naming conventions apply. 


Each identifier in the USING actual-parameter-list clause must be defined as either 

a 77-level item that resides in the stack or a 01-level item. Items must correspond 

in level-number, usage, and size to those described in the corresponding positions 

of the USING clause of the PROCEDURE DIVISION in the called program. The . 
exceptions are DISPLAY, COMP, BINARY group items, and 77-level BINARY items with 
RECEIVED BY REFERENCE clauses. These items are interchangeable as parameters 
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of tasking CALL statements only; that is, each item can be passed to and received by the 
other items when the system is doing tasking calls. However, the lengths must be the 
same, or run-time errors, such as INVALID INDEX, occur. 


The identifiers in the USING clause can be any combination of data items, task 
(control point) items, INDEX items, EVENT items, or lock items at either the group or 
elementary level. 


The USING clause is included in the CALL statement if there is a USING clause in the 
USE statement of section-name, in the PROCEDURE DIVISION header of the called 
program, or both. The number, type, and order of items in each USING clause must be 
identical, except that DISPLAY, COMP BINARY, REAL, and DOUBLE group items, 
and 77-level BINARY REAL, and DOUBLE items with RECEIVED BY REFERENCE 
clauses are interchangeable as parameters of tasking CALL statements. That is, each 
item can be passed to and received by the other. You must take care to ensure that the 
lengths of different types of items are the same, or run-time errors might occur. 


Table 9-3 describes the matching of formal parameters between the COBOL74, ALGOL, 
and COBOL68 languages. 


Table 9-3. Parameter Mapping for Tasking Calls 


COBOL74 Parameter ALGOL Parameter COBOL68 Parameter 


77-level BINARY or REAL REAL INTEGER 77-level COMP or COMP-4 
item (single precision) item (single precision) 


77-level BINARY or DOUBLE 77-level COMP or COMP-5 
DOUBLE item (double _ item (double precision) 
precision) 


01-level DISPLAY, COMP, REAL ARRAY [*] 01-level DISPLAY, COMP, or 
BINARY, REAL, or DOUBLE COMP-2 group item with or 
item without LOWER-BOUNDS 


INTEGER ARRAY [*] 
EBCDIC ARRAY [*] 
HEX ARRAY [*] 
REAL ARRAY [0] 
INTEGER ARRAY [0] 
EBCDIC ARRAY [0] 
HEX ARRAY [0] 


77-level EVENT or LOCK EVENT 77-level EVENT or LOCK 
item . . item 


77-level or 01-level TASK TASK 77-level or 01-level TASK 
elementary item elementary item — 


continued 
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Table 9-3. Parameter Mapping for Tasking Calls (cont.) 


COBOL74 Parameter ALGOL Parameter COBOL68 Parameter 


01-level EVENT or LOCK EVENT ARRAY '  77-level EVENT or LOCK 
group item . group item 


01-level TASK group item _ TASK ARRAY O1-level TASK group item 


FILE ; FILE FILE 


The following notes describe the use of actual parameters and their correspondence to 
ALGOL variable types: 


e BINARY items are single precision when they are declared with a length of 11 digits 
or less. These items are double precision if they are declared with a length of 12 to 
23 digits. While BINARY items can match ALGOL REAL or INTEGER parameters, 
they are maintained in binary-coded format; their values are maintained with 
exponents of zero and no fractional parts. 


e ABINARY 01-level group item with elements that are double precision (length of 12 
to 23 digits) is not represented as a double array. Each BINARY 01-level item isa 
real array. Two array elements are used for each item with a length of 12 to 28 digits 
(double) and one array element is used for each item with a length of 1 to 11 digits 
(single precision). ALGOL programs accessing the double-precision elements must 
use a double array equated to the real array that was used to receive or send the 
parameter. The ALGOL real array must be long enough to allow two elements for 
each item with a length of 12 to 23 digits. 


e 77-level DISPLAY and COMP items are not allowed as parameters in COBOL74 . 
tasking. . 
e An ALGOL subprogram that declares global libraries can be bound to a COBOL74 


host program. However, all entry points of the libraries must be used in CALL 
statements in the COBOL74 program for the program to bind successfully. 


Any array row passed to or from an ALGOL-like language is considered a 01-level 
record in COBOL74. For example, consider an ALGOL program with an external 
procedure declaration specifying a formal parameter EBCDIC ARRAY A[*]. If 

this declaration is used to call a COBOL74 program that has a formal DISPLAY 
item parameter, the ALGOL-supplied array row is treated as a DISPLAY item 

of whatever length is declared in the COBOL74 program; the array row must be 

the declared length. The lower-bound could have been fixed when specified in the 
ALGOL procedure declaration (for example, A[0] or A[1]), instead of variable bound 
(A[*]); COBOL74 is not affected by the ALGOL lower-bound. 


e Inthe opposite direction, (a COBOL74 item passed to an ALGOL procedure), the 
COBOL74 item is treated as an ALGOL array row; its length is determined by the 
. COBOL74 declaration. If the ALGOL procedure specifies a variable bound (A[*)), 
the actual value of the lower-bound is 0 (zero). 


8600 0296-000 . | 9-15 


PROCEDURE DIVISION Statements 


The Work Flow Language (WFL) calls programs as tasks, passes its string parameters as 
real arrays with lower-bounds, and passes its numeric variable and constant parameters 
by value as real, single-precision operands. Table 9-4 shows WI'L parameters and the 
corresponding COBOL74 parameters. 


Table 9-4. WFL and COBOL74 Parameters 


WEL parameter COBOL74 parameter 


STRING or STRING constant DISPLAY, COMP or BINARY group item 


REAL, INTEGER, REAL constant or INTEGER 77-level BINARY or REAL item (single 
constant precision) 


Format 2 (Unisys Extension) 


CALL section-name [ USING actual-parameter-list | 


Explanation of Format 2 


Format 2 invokes as a procedure an externally compiled program that must have been 
bound into the calling program. The procedure is bound into the calling object code and 
is physically part of the program itself. 


The actual parameter-list must consist of data items, control items, and expressions 
optionally separated by commas. 


Table 9-5 shows the formal parameters for bound and host programs that can be 
declared in COBOL74, along with the corresponding declarations in ALGOL and the 
permissible kinds of actual parameters that can be passed. 


Note that if the formal parameter in COBOL74 or COBOL68 is a 77-level BINARY item, 


. the actual parameter can be the value of an arithmetic expression. A single item of any 
numeric type can be considered an arithmetic expression for this purpose. 
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Table 9-5. Parameters for Bound and Host Programs 


COBOL74 Formal Permissible Actual 
Parameter ALGOL Formal Parameter Parameter 


BINARY, 77 1-11 digits INTEGER | Arithmetic-expression 
(RECEIVED BY CONTENT) 


REAL, 77 (RECEIVED BY Arithmetic-expression 
CONTENT) 


BINARY, 77 12-23 digits or DOUBLE Arithmetic-expression 
DOUBLE, 77 (RECEIVED ; 
BY CONTENT) 


BINARY, 77 1-11 digits INTEGER BINARY, 77 1-11 digits 
(RECEIVED BY 
REFERENCE) 


REAL, 77 (RECEIVED BY REAL, 77 
REFERENCE) 


BINARY, 77 12-23 digits DOUBLE BINARY, 77 12-23 digits 
(RECEIVED BY | 
REFERENCE) 


DOUBLE, 77 (RECEIVED DOUBLE DOUBLE, 77 
BY REFERENCE) 


EVENT or LOCK, 77 EVENT EVENT or LOCK, 77 


TASK, 77 or O1 TASK TASK, 77 or 01 


BINARY, 01 INTEGER ARRAY BINARY, COMP, or DISPLAY, 
) 


REAL, 01 REAL ARRAY REAL, 01 
DOUBLE, 01 REAL ARRAY _ REAL or DOUBLE, 01 


COMP or DISPLAY, 01 EBCDIC ARRAY BINARY, COMP, or DISPLAY, 
— 01 


EVENT or LOCK, 01 group EVENT ARRAY EVENT or LOCK, 01 group 


continued 
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Table 9—5. Parameters for Bound and Host Programs (cont.) 


COBOL74 Formal Permissible Actual 
Parameter ALGOL Formal Parameter Parameter 


TASK, 01 group TASK ARRAY _ TASK, 01 group 


FILE FILE FILE 


Format 3 (Unisys Extension) 


The execution of a CALL SYSTEM DUMP statement causes control to pass to the 
DUMP routine in the operating environment. 


CALL SYSTEM DUMP 


Explanation of Format 3 


The CALL SYSTEM DUMP statement causes the operating system to dump data from 
the memory area of the program. 


Format 4 (Unisys Extension) 


CALL SYSTEM WFL USING { 


, identifier-1 
, literal-1 “ 


Explanation of Format 4 


The CALL SYSTEM WEL statement causes an independent task to be initiated by 
submitting a Work Flow Language (WFL) job to the WFL compiler. After initiating the 
task, the executing program does not wait for the initiated task to be completed but 
immediately proceeds to execute the next statement. 


The CALL SYSTEM WEL statement requires one parameter that can be a nonnumeric 
literal or the name of a 01-level data item with the USAGE IS DISPLAY phrase. The 
contents of the parameter must be a complete WFL job. (Refer to the A Series Work 
Flow Language (WFL) Programming Reference Manual for information on WFL jobs.) 
The syntax of the WFL job deck is not checked by the COBOL compiler; thus any error 
detected by the WFL compiler has no direct effect on the calling program. 


9-18 | 8600 0296-000 


PROCEDURE DIVISION Statements 


Note: Previously, the CALL SYSTEM WFL statement invoked the old WFL 
Job by default. On the Mark 3.7 and later releases, the content of the 
parameter specified by the CALL.SYSTEM WEL statement is treated 
as a new WFL job by default. Old WFL is a less powerful version of 
WEL. Old WFL jobs begin with JOB, USER, CLASS, or a specific 
statement starter (not BEGIN). New WFL jobs begin with the phrase 
BEGIN JOB. For more information on WFL, see the WFL Reference 
Manual 


To minimize the number of changes to existing programs, “old” WFL 
is tried if a syntax error is found in “new” WFL. Jobs that start with 
an explicit job heading — for example, BEGIN JOB (new WFL) or 
JOB (old WFL)—are still processed according to the specification in 
the job heading; these jobs are not affected by this change. 


CAUSE (Unisys Extension) 


The CAUSE statement is normally used for communication between processes in an 
asynchronous processing environment. 


The format of the CAUSE statement is as follows: 


CAUSE [ AND RESET | event-identifier-1 [ , event-identifier-2 ]... . 


Explanation of Format 


The CAUSE statement initiates the events specified by the event-identifiers. If 

any process is in a Suspended condition because the program encountered a WAIT 

event-identifier statement that specified one of these event-identifiers, it resumes 

processing. If any process has an interrupt procedure attached to one of these events, 
. the interrupt mechanism is initiated. 


When the AND RESET phrase is specified, all the event-identifiers are SET and then 
immediately RESET. This action indicates to any process that has an interrupt procedure 
attached to one of the event-identifiers that the event has been caused. ; 


Event-identifiers must be one of the following: 


e Properly qualified and subscripted data-names with the USAGE EVENT phrase 
specified 


e File or task attributes of type EVENT — 
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See Also 
e For information about executing an interrupt procedure that has been attached to an 
EVENT item, refer to “ALLOW (Unisys Extension)” in this section. 


e For information about associating an interrupt procedure with an EVENT item, 
_ refer to “ATTACH (Unisys Extension)” in this section. 


e For information about dissociating a procedure from a task item or an EVENT item, 
refer to “DETACH (Unisys Extension)” in this section. 


e For information about preventing execution of an interrupt procedure that has been 
attached to an event, refer to “DISALLOW” in this section. 


e For information about suspending the execution of an object program, refer to 
“WAIT (Unisys Extension)” in this section. 


CHANGE (Unisys Extension) © 


The CHANGE statement modifies a file attribute or a task attribute. 


Those attributes that cannot be changed at any time cannot be specified ina CHANGE 
statement. 


Certain attributes cannot be changed while the file is in open mode. Attempts to change 
these attributes while the file is open are ignored. 


Certain file attributes are also used by the compiler to implement various constructs in 
the declaration of and access to files within the program. When a file attribute can be set 
or declared using standard COBOL syntax, it is always preferable to use the standard 
syntax because changing the attribute can lead to unexpected results in cases when the 

- attribute is also used or altered by the compiler. 


The CHANGE statement has the following three formats: 


Format Explanation 
1 _ Changes a numeric or alphanumeric file attribute 
2 Changes a mnemonic file attribute 
3 Changes a task attribute 
Format 1 


CHANGE eee \ 


alphanumeric-file-attribute-identifier 


TO . 
UP BY ae 
DOWN BY identifier-1 
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Explanation of Format 1 


If a numeric file attribute-identifier is specified, literal-1 must be a numeric literal, and 
identifier-1 must be a numeric data item that represents an integer. 


If an alphanumeric-file-attribute-identifier is specified, literal-1 must be a nonnumeric 
literal and can end with a period, and identifier-1 must be a nonnumeric DISPLAY data 
item and must end with a period. 


Attempts to change attributes to illegal values are ignored. 


The UP BY and DOWN BY phrases are for use with the STATIONLIST attribute only. 
The STATIONLIST attribute can be used only with REMOTE files. 


Format 2 


CHANGE mnemonic-file-attribute-identifier TO 


y mnemonic-attribute-value 


Explanation of Format 2 
The mnemonic-attribute-value must be associated with the attribute specified. 


If there is a data-name with the same name as a mnemonic-attribute-value, the value 
assigned to the attribute is determined by using the optional word VALUE. If the 
word VALUE is present, the attribute is set to the value of the mnemonic. If the word 
VALUE is omitted, the attribute is set to the current value of data-name. 


/ 


Format 3 


identifier-2 

literal-2 
VALUE 

{vs 


CHANGE task-attribute-identifier TO 


} task-attribute-mnemonic 


Explanation of Format 3 


Identifier-2 or literal-2 or the task-attribute-mnemonic must be consistent with the type 
of the task-attribute-identifier. Each of these variables can end with a period. Task 
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attributes of attribute list type should not end with a period. For example, the LIBRARY 
task attribute should not end with a period. ; 


The choice of identifier, literal, or task-attribute-mnemonic depends on the attribute 
being changed and its declared value. Type POINTER task attributes accept an 
alphanumeric item. 


Boolean or INTEGER task attributes accept a numeric item or a literal or the value 
associated with a mnemonic. If the value is not in the permissible range for the attribute 
specified, an error occurs either at compilation time or at execution time. 


A task-attribute-mnemonic is a name associated with a constant value for an attribute 
that has a set number of predetermined possible values. 


If there is a data-name with the same name as a task-attribute-mnemonic, the value 
assigned to the attribute is determined by using the optional word VALUE. If the 
word VALUE is present, the attribute is set to the value of the mnemonic. If the word 
VALUE is omitted, the attribute is set to the current value of data-name. 


See Also 

e Fora description of the format of task-attribute identifiers, refer to “Task-Attribute 
Identifiers (Unisys Extension)” in Section 3, “File and Task Concepts.” 

e For information on file attributes, refer to the File Attributes Reference Manual. 


e For information on task attributes, refer to the Task Attributes Reference Manual. 


CLOSE 


The CLOSE statement ends the processing of a file or of a reel of a multivolume tape file. 
Unlike the OPEN statement, you do not have to specify the open mode of the file (for 
example, input). However, you do have to consider the device associated with the file. 
Some close options are not permitted for a particular device, and some close options 
cause different actions with different devices. The CLOSE statement does not affect the 
contents or availability of the record area of the file (This is a Unisys extension). 


The CLOSE statement has the following three formats for files: 


Format Explanation 
1 Closes a file for sequential /O applications 
2 | Closes a file for relative and indexed I/O applications 
3 Closes a port file 
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Format 1: Sequential I/O 


Format 1 is for files with sequential organization. The format is as follows: 


REEL 
~ | UNIT 


i! FOR REMOVAL | 


NO REWIND 
: LOCK 
CLOSE ‘| file-name SAVE [ FOR REMOVAL | 


WITH { PURGE 
| CRUNCH 
RELEASE 
REMOVE [ CRUNCH ] 


Explanation of Format 


The explanation of the format notation is divided into the following three categories of 
devices: 

_@ Devices other than tape 
e Single-reel tape 
° Multiple-reel tape 


Devices Other Than Tape 


For a file associated with a disk, printer, punch, reader, or remote device, the concept 
of a reel has no meaning. If you specify the REEL or UNIT option for these files, the 
system ignores the CLOSE statement and does not close the file. If you specify the NO 
REWIND or SAVE FOR REMOVAL option, the system ignores the option, but closes 
the file. 


For these files, the CLOSE statement affects only the association between the logical 
file and the physical file, not the physical device. The operating system controls the 
assignment and disposition of the physical devices. (This is a Unisys extension). 

For each close option, there is a list of actions called dispositions that apply when you 


use that option. Refer to Table 9-6 later in this section for the details about each close 
disposition. : 


Explanation of Format for Devices Other Than Tape 


The CLOSE statement closes the file and applies the retain file disposition. 
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The file-name names an open file that you want to close. The file must be named and 
assigned to a device in the SELECT clause and described in the INPUT-OUTPUT and 
FILE SECTIONSs of your program. You can close files of differing Crepmizaucne oe 
access types in one CLOSE statement. 


The LOCK phrase dipues the file and applies the following dispositions: 


e Lock file 
e Release file 


e Release device 
The SAVE phrase closes the file and applies the following dispositions: 


e Save file 


e Release file 
The PURGE phrase closes the file and applies the purge file disposition. 
The CRUNCH phrase closes the file and applies the following dispositions: 


e Crunch file 
e Save file 


e Release file 
The RELEASE phrase closes the file and applies the following dispositions: 


e Release file 


e Release device 
The REMOVE phrase closes the file and applies the following dispositions: 


e Save file with remove 


e Release file 


The REMOVE CRUNCH phrase closes the file and applies the following dispositions: 


e Crunch file 

e Save file with remove 

e Release file 
Single-Reel Tape 


A single-reel tape file is a sequential file that is entirely contained on one reel. 
For each close option, there is a list of actions called dispositions that apply when you 


use that option. Refer to Table 9-6 later in this section for the details about each close 
disposition. 
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Explanation of Format for Single-Reel Tape 

The CLOSE phrase closes the file and applies the following dispositions: 
e Rewind reel 

e Retain file 


The file-name names an open file that you want to close. The file must be named and 
assigned to a tape in the SELECT clause and described in the INPUT-OUTPUT and 
FILE SECTIONSs of your program. You can close files of differing organizations and 
access types in one CLOSE statement. If an output tape is to contain more than one 
file, the file is closed but the tape is not rewound. This process enables you to write 
subsequent output files to the same tape. 


The NO REWIND phrase closes the file and applies the following dispositions: 
e Norewind of current reel 

e Retain file 

The LOCK phrase closes the file and applies the following dispositions: 


e Lock file 
e Rewind reel 
e Release file 


e Release device 
~The SAVE FOR REMOVAL phrase closes the file and applies the following dispositions: 


e Rewind reel 
_@ Release device 
e Release file | 


e Save reel 
The PURGE phrase closes the file and applies the following dispositions: 


e Rewind reel 


e Purge file 
The RELEASE phrase closes the file and applies the following dispositions: 


e Rewind reel 
e Release file 


e Release device 
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Multiple-Reel Tape 


A multiple-reel tape file is a sequential file that is contained on more than one reel. If 
you are processing very large multiple-reel files, the following close options might be 
useful. These options enable you to access the next reel of tape without requiring and 
intervening OPEN statement. 


For each close option, there is a list of actions called dispositions that apply when you | 
use that option. Refer to Table 9-6 later in this section for the details about each close 
disposition. | 


Explanation of Format for Multiple-Reel Tape 


The CLOSE statement closes the file and applies the following dispositions: 


‘e ~©. Rewind reel 
e Previous reels unaffected 


e Retain file 


The file-name names an open file that you want to close. The file must be named and 

assigned to a tape in the SELECT clause and described in the INPUT-OUTPUT and 

FILE SECTIONSs of your program. You can close files of differing organizations in one 
_CLOSE statement. 


The REEL or UNIT phrases do not close the file and apply the following dispositions: 


e Close reel 


e Rewind reel 
The REEL and UNIT phrases are synonymous and interchangeable. 


The REEL FOR REMOVAL phrase does not close the file and applies the following 
dispositions: 


e Close reel 


e No rewind of current reel 
The NO REWIND phrase closes the file and applies the following dispositions: 


e Retain file 
e No rewind of current reel 
e Previous reels unaffected 


The LOCK phrase closes the file and applies the following dispositions: 


e Lock file 
e Rewind reel 


e Release file . 
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e Previous reels unaffected 


e Release device 
The SAVE FOR REMOVAL phrase closes the file and applies the following dispositions: 


e Rewind reel 

e Previous reels unaffected 
e Lock file 

e Release file 

e Release device 


e Save reel unit 
The PURGE phrase closes the file and applies the following dispositions: 


e Rewind reel, . 
e Previous reels unaffected 
e Purge file 


The RELEASE phrase closes the file and applies the following dispositions: 


- @ Rewind reel 
e Previous reels unaffected 
e Release file 


e Release device 


Close File Dispositions 


A-close file disposition is an action taken by the system during the closing procedures for 
a file. For a specified close option, the dispositions that occur depend on the device with 
which the file is associated. For example, a simple CLOSE statement with no 0 options 
specified also rewinds a tape file. 


A file must be in open mode to be closed. If a file is open when a program ends 
abnormally, executes a STOP RUN statement, or performs a CANCEL statement for the 
program that uses the file, the program closes the file using the dispositions of a CLOSE 
statement with no options specified. 


The system ignores the NO REWIND, FOR REMOVAL, SAVE, PURGE, CRUNCH, 
RELEASE, and REMOVE neers if they do not apply to the device associated with the 
file. 


Once a file is closed, the program cannot perform any statement that refers to the 

file until the file is reopened. Because the SORT and MERGE statements have their 
own routines, this restriction does not apply when the program performs a SORT or a 
MERGE statement with the USING or GIVING options specified. | 
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If the program attempts to close an optional input file that is not present, the program 
does not perform the standard end-of-file processing for that file. You can designate 
an optional file with the OPTIONAL phrase of the FILE-CONTROL paragraph in the 
ENVIRONMENT DIVISION. 


When the program closes a file and releases it to the system, the program also checks 

~ the value of the EXCLUSIVE file attribute. If the value of the attribute is TRUE, 
the program sets it to FALSE. The CLOSE statement also changes the value of the 
FILEUSE attribute to I-O. This change might affect the results of any subsequent access 
to the RESIDENT, PRESENT, or AVAILABLE file attribute. . 


Table 9-6 lists each close disposition in alphabetical order and explains its actions. If the 
disposition depends on whether or not the file is an input, an output, or an I/O file, the 
differences between the open modes are described. Otherwise, the disposition applies to 
input, output, and I/O files. : 


Table 9-6. Close-File Dispositions for Sequential I/O 


Disposition Explanation 
Close reel For input files, the following operations OCCUr: 
e Reels are swapped. 
e Standard beginning-reel label procedure is performed. 


The next READ statement performed for that file makes the next data 
record on the new reel available. 


For output files, the following operations occur: 

e Standard ending-reel label procedure is performed. 

@ Reels are swapped. 

e Standard beginning-reel label procedure is performed. 


The next WRITE statement performed on the file directs the next data 
record to the next reel of the file. 


Crunch file Releases as available to the system any unused portions of storage areas 
allocated for the file. This disposition is valid only for disk files. The file 
cannot subsequently be extended by opening the file with the OPEN 
EXTEND statement.t 


Lock file Locks the logical file so that it cannot be reopened during execution of 
the program. If the file is assigned to disk, it becomes a permanent file 
before being made unavailable. If the file is assigned to tape, the 
physical unit is unreadied. 


No rewind of Leaves the current reel in its current position. 
current reel 


continued 
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Table 9-6. Close-File Dispositions for Sequential I/O (cont.) 


Disposition Explanation 


Previous reels Rewinds and locks all reels in the file prior to the current reel (except 
unaffected reels controlled by a prior CLOSE REEL statement). 


If the file is an input file, it remains open and cannot be opened in the 
program. lf the current reel is not the last one in the input file, the 
program does not process the remaining reels. 


Purge file If the file is a tape file, the system rewinds the reel. If the reel has a write 
ring, the system writes a scratch label on it and releases the device as 
available to the system. If the file is a permanent disk file, the system 
removes the file-name from its directory and releases the disk area 
occupied by the file as available to the system.t 


Release device Releases the device so that it is available to the system if the device to 
which the file was assigned can be controlled by the object program.t 


Release file Severs the association between the logical file and the physical file. As 
the file is closed, the system checks the value of the EXCLUSIVE file 
attribute. If the value of the attribute is TRUE, it is assigned the value 
FALSE during the close process. The program releases to the system the 
areas of memory allocated for buffers.+ 


Remove file Rewinds the current reel and releases it to the system. However, you can 
access the reel again in its proper order of reels within the file if you 

perform a CLOSE statement without the REEL phrase, followed by an 

OPEN statement for the file. 


Retain file Retains the association between the logical file and the physical file. 
When you reopen the file, the operating system does not search for the 
physical file.t 


Rewind reel Positions the current reel or analogous device at its physical beginning. 


Save file Suspends the program if a perrnanent file with the same title already 
exists and the system option 5 (AUTORM) is reset. To restart the 
program, the operator must enter either the RM (Remove) or OF 
(Optional file):system command. The new file becomes permanent after 
the operator enters the RM or OF command when the system option 5 

(AUTORM) is set, or if no old file with the same title exists. This 

disposition is valid only for disk files. The file can be reopened during the 

execution of the program.t 


Save file with Makes the file permanent. if a permanent file with the same title already 

remove exists, the system removes it without regard for system option 5 . 
(AUTORM). This disposition is valid only for disk files. The program can 

reopen the file while the program is executing. t 


Save reel unit Unreadies the physical tape unit containing the reel. 


t Unisys extension 
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Format 2: Relative and Indexed I/O 


9-30 


Indexed and relative files must be associated with a disk device. If the program closes 
and releases the file to the system, the program checks the value of the EXCLUSIVE file 
attribute. If the value is TRUH, it is set to FALSE during the close process. 


To close a relative or an indexed file, use the syntax shown in Format 2. 


LOCK 
| SAVE 
CLOSE | filename | WITH ( PURGE 


RELEASE 
REMOVE 


Explanation of Format 


The CLOSE statement closes the logical file. The program retains the association 
between the logical file and the physical file. If you reopen the file, the system does not 
search for the physical file (Unisys extension). 


The file-name names identifies an open relative or indexed file that you want to close. 
The file must be named and assigned to DISK in the SELECT clause and described in 
the INPUT-OUTPUT and FILE SECTIONSs of your program. You can close files of 
differing organizations and access types in one CLOSE statement. 


The LOCK phrase closes the logical file and locks it so that the file cannot be reopened 
during the execution of the program. However, the system makes the physical file 
permanent and removes any existing file with the same name. The program severs the 
association between the logical file and the physical file and releases to the system the 
areas of memory allocated for buffers (Unisys extension). 


The SAVE phrase closes the logical file and suspends the program if a permanent 

file with the same title exists. The operator must enter either the RM (Remove) or 

the OF (Optional file) system command to restart the program. The new file becomes 
permanent after the operator enters the RM or OF system command, if system option 5 
(AUTORM) is set, or if no file with the same title exists. You can reopen the file during 
the execution of the program. The program severs the association between the logical 
file and the physical file and releases to the system the areas of memory allocated for 
buffers (Unisys extension). 


The PURGE phrase closes the logical file. If the file is permanent, the system removes 
the file-name from the system directory and releases to the system the areas occupied by 
the file. 


The RELEASE phrase closes the file. 
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The REMOVE phrase closes the logical file and makes the physical file permanent. Ifa 
permanent file with the same title already exists, the system removes it without regard 
for system option 5 (AUTORM). You can reopen the file during execution of the program 
(Unisys extension). 


Format 3: Port Files (Unisys Extension) 


You can close a port file by performing a CLOSE statement using the syntax shown in 
Format 3. 


CLOSE file-name | WITH { NO WAIT } | 


WAIT 


CLOSE-DISPOSITION OF cae } 


ORDERLY 
identifier-1 

integer } 

a 

literal } 


USING <¢ ASSOCIATED-DATA-LENGTH OF { 


ASSOCIATED-DATA OF { 


Explanation of Format 
The file-name names a port file. 


The NO WAIT phrase closes the dialogue and returns control to the program without 
waiting for the correspondent endpoint to close its subfile. The close operation continues 
in parallel with the execution of the program. The subfile is not closed completely until 
the correspondent endpoint closes its subfile. 


The WAIT option closes the dialogue and suspends the program until the correspondent 
endpoint has closed its subfile too. If a WITH option is not specified, the program 
defaults to the WITH WAIT option. 


The USING option permits each of the USING clauses to be included once only. 

The CLOSE-DISPOSITION ABORT phrase closes the dialogue immediately, without 
ensuring that your program received all the data. It is your responsibility to guarantee 
that all messages are processed so there is no loss of data. The compiler will default to 
the ABORT phrase if the type of CLOSE-DISPOSITION is not specified. . 


The CLOSE-DISPOSITION ORDERLY phrase closes the dialogue in an orderly manner 
and ensures that no data is lost. This disposition is available only with some services. 


The ASSOCIATED-DATA-LENGTH phrase specifies the number of characters to be 
sent. If you do not specify the length of the associated data and the associated data is 
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a data item, your program uses the actual length of the data. If you specify the length 
of the associated data, the length value must be less than or equal to the actual length 
of the data. An error results if the length specified is not a single-precision integer 
value. To use the ASSOCIATED-DATA-LENGTH phrase, you must specify the 
ASSOCIATED-DATA phrase with either an identifier or an undigit literal, but nota _ 
nonnumeric literal. 


The ASSOCIATED-DATA phrase is used on some types of networks to transfer data to 
the correspondent endpoint along with the request to close the dialogue. 


The integer must be a numeric literal. 
Identifier-1 must name an elementary integer data item. 
Identifier-2 can be a group data item or an alphanumeric elementary data item. 


; \ 
The literal can be a nonnumeric literal or an undigit literal. 


General Rules 


Besides specifying the close options, you might need to designate the subfiles to close. If 
you.are using subfiles, perform the following steps: . 


1. Specify the total number of subfiles in your program by using the CHANGE 
ATTRIBUTE MAXSUBFILES TO VALUE attribute-value statement. 


2. Specify the subfiles to be opened by using the SELECT port-file ASSIGN TO 
PORT; ACTUAL KEY IS subfile-num clause. 


3. Declare subfile-num and attribute-value in the WORKING-STORAGE SECTION. 


The ACTUAL KEY clause specifies the subfile to close. Table 9~7 shows the subfiles that 
are closed with differing ACTUAL KEY clause values. 


Table 9-7. Designating Subfiles to Close 


Actual Key Value . Explanation | 


O or none Closes every open subfile 
Nonzero Closes the specified subfile 


Greater than the MAXSUBFILES Returns a BADSUBFILEINDEX run-time error in the 
value or negative number SUBFILERROR attribute 


Examples 
In the following examples, it is assumed that earlier in the program the port files were 


declared using an ACTUAL KEY clause and the subfile index was set to a particular 
subfile. 
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Example 9-6 causes the dialogue established on the port file for PORTFILE1 to be 
closed. The program is suspended until the correspondent endpoint is also closed. 


CLOSE PORTFILE1 WITH WAIT. 
Example 9-6. Coding a CLOSE WITH WAIT Statement 


Example 9-7 closes the dialogue and returns control to the program without waiting 
for the correspondent endpoint to close its subfile. The subfile on PORTFILE1 is not 
completely closed until the correspondent endpoint closes its subfile. The ORDERLY 
option ensures that no data is lost during the close operation. Any messages that are 
received are saved in the READ queue. 


CLOSE PORTFILE1 WITH NO WAIT USING CLOSE-DISPOSITION OF ORDERLY. 
Example 9-7. Coding a CLOSE WITH NO WAIT Statement 


Example 9-8 requests that PORTFILE1 be closed. Since the CLOSE-DISPOSITION 
phrase is not specified, a CLOSE ABORT statement is assumed. Since the WAIT or NO 
WAIT are not specified, WAIT is assumed, and control is not returned to the program 
until the close operation is complete. The information "MYDATA" is sent to the other 
program with this message: 


CLOSE PORTFILE1 USING ASSOCIATED-DATA OF "MYDATA". 
Example 9-8. Coding a CLOSE...ASSOCIATED-DATA Statement 


Example 9-9 requests that PORTFILE1 be closed. When this message to close is sent, 
10 characters of data are sent at the same time to the correspondent endpoint. The data 
sent begins at the location pointed to by the ALPHANUM-ITEM item. 


CLOSE PORTFILE1 
~ USING ASSOCIATED-DATA OF ALPHANUM-ITEM 
ASSOCIATED-DATA-LENGTH OF 18. 


Example 9-9. Coding a CLOSE...ASSOCIATED-DATA-LENGTH Statement 


Example 9-10 requests that the multiple port files, PORTFILE1 and PORTFILE2, be 
closed. The ABORT option closes the dialogue, but does not ensure that your program 
received all the data. 


CLOSE PORTFILE1 WITH WAIT 

USING CLOSE-DISPOSITION OF ABORT 
ASSOCIATED-DATA-LENGTH OF 19 
ASSOCIATED-DATA OF ALPHANUM-ITEM 

PORTFILE2 WITH NO WAIT 

USING CLOSE-DISPOSITION OF ORDERLY 
ASSOCIATED-DATA-LENGTH OF 18 
ASSOCIATED-DATA OF ALPHANUM-ITEM. 


Example 9-10. Closing Multiple Port Files 
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See Also 


e For step-by-step information on coding port file applications, refer to the I/O 
Subsystem Programming Guide. 


e For information on file attributes, refer to the File Attributes Reference Manual. 


1/O Status Value 


The system returns a value that indicates the result of a CLOSE statement. You can 
access this value by including a SELECT file-name FILE STATUS IS data-name clause 
in your program. The operating system moves a value into the designated data-name 
storage area after the program performs the CLOSE statement. You can then use an 
IF statement to test the value of the data-name and take the desired action depending 
on the result. If you choose not to code an action for me I/O result, the system provides 
default actions for the results. 


If your program does not include either a FILE STATUS clause or an ERROR 
PROCEDURE clause in the DECLARATIVES SECTION for the file, the system aborts 
the program when the close operation is unsuccessful. 


Table 9-8 shows the I/O status values and their meanings. 


Table 9-8. I/O Status Values for CLOSE Statement Completion 


Value ; Explanation ; 


Control was returned to the program after the CLOSE statement completed 
correctly. In the case of a port file, the close operation might be pending. 


An error was detected while the file was being closed. 


- t+ Unisys extension 


COMPUTE 


The COMPUTE statement calculates the value of the arithmetic expression following 
the equal sign (=) and assigns the value to one or more data items preceding the equal 


sign. 
This statement is useful for performing complex arithmetic operations. 


The general format of this statement is as follows: 


COMPUTE identifier-1 [ ROUNDED ] | , identifier-2 [ ROUNDED ] ]... 


= arithmetic-expression | ; ON SIZE ERROR imperative-statement | 
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Explanation of Format 


If more than one identifier is specified to the left of the equal sign, the compiler 
computes the value of the arithmetic expression and stores the new value in identifier-1, 
identifier-2, and so forth in turn. 


Identifiers that appear only to the left of the equal sign must refer either to an 
elementary numeric item or to an elementary numeric-edited item. 


If the arithmetic expression consists of a single identifier or literal, the compiler sets the 
values of identifier-1, identifier-2, and so on to the value of the single identifier or literal. 


Imperative-statement can be the NEXT SENTENCE phrase. 


When a sending item and a receiving item in the same COMPUTE statement share a 
part, but not all, of their storage areas, the result of the execution of the statement is 
undefined. 


Note: A rounding error can occur if identifier-1, identifier-2, and so on 
contain different numbers of digits after the decimal point, and if an 
intermediate result of the computation exceeds the maximum integer. 


_ See Also 


e Fora description of the features common to the arithmetic statements, refer 
to “Common Rules for Arithmetic Statements” in Section 8, “PROCEDURE 
DIVISION Concepts.” 


e For information on producing multiple results with one arithmetic statement, refer 
to “Calculating Multiple Results with One Arithmetic Statement” in Section 8, 
“PROCEDURE DIVISION Concepts.” 


e For information about the rounding of arithmetic result fields, refer to “ROUNDED 
Phrase” in Section 8, “PROCEDURE DIVISION Concepts.” 


e For information on Size Error conditions, refer to “SIZE ERROR Phrase” in 
Section 8, “PROCEDURE DIVISION Concepts.” 


CONTINUE (Unisys Extension) 


The CONTINUE statement passes control to a synchronous process that has been 
previously called and exited with the EXIT PROGRAM or EXIT PROGRAM RETURN 
HERE statement. This statement enables the called process to restart without 
repassing parameters or to resume at a point other than its first executable statement. — 


The general format of this statement is as follows: 


CONTINUE task-identifier 
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Explanation of Format 


The task-identifier must be the same as in a previously executed CALL statement. 


See Also 


For information about transferring control to a separate task or procedure, refer to 
“CALL” earlier in this section. 


COPY 


The COPY statement incorporates text from a library program into the COBOL poe 
that contains the COPY statement. 


When the compiler processes a COPY statement, it copies the library text associated 
with the text-name into the source program and logically replaces the entire COPY 
statement, beginning with the reserved word COPY and ending with the period, 
inclusive. 


You can use a COPY statement in the source program anywhere a character string or 
a separator is allowed, but a COPY statement must not occur within another COPY 
statement. 


The text produced as a result of the complete processing of a COPY statement must not 
contain a COPY statement. 


Text in the copied library must conform to the rules for COBOL reference format. 
The compilation of a source program containing COPY statements is logically equivalent 
to processing all COPY statements prior to the processing of the resultant source 


program. 


This statement is useful for eliminating redundant programming. 
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The general format of this statement is as follows: 


COPY text-name | a library -name| ...[ ON family-name | 


THROUGH 
| FROM sequence-number-1 fae sequence-number-2 | | 
TO 


identifier-1 
literal-1 
REPLACING 4 ‘word-1 
== pseudotext- 
identifier-2 
literal-2 
word-2 


== pseudotext-1 = = 
| BY 
Q= 


Explanation of Format 
The COPY statement must be preceded by a separator and ended by a period. (The use 
‘of a separator other than a space immediately before a COPY statement is a Unisys 


extension). To comply with language standards, at least one space must be used as a 
separator immediately before a COPY statement. 


text-name 


Text-name specifies the external identification of a file in the COBOL library. 


library-name 
Library-name specifies the external identification of a directory-ID associated with the 


name of the COBOL library. Successive library-names specify parent directory-IDs; 
thus, a complete series of library-names represents the entire name. 


ON family-name (Unisys Extension) . 


Family-name specifies the name of the family in which the library file resides. 


FROM sequence number (Unisys Extension) 


THRU, THROUGH, and TO are synonyms. 
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If the FROM phrase is specified, copying starts at the sequence number specified. If 
the THRU phrase is specified, copying continues until that sequence number has been 
copied. If the THRU phrase is not specified, copying continues to the end of the file. 


REPLACING 


If the REPLACING phrase is not specified, the library text is copied unchanged. If the 
REPLACING phrase is specified, the library text is copied, and each properly matched 
occurrence of pseudotext-1, identifier-1, word-1, or literal-1 in the library text is replaced 
by the corresponding pseudotext-2, identifier-2, word-2, or literal-2. The REPLACING 


-phrase does not alter the source library itself, but changes the library text according to 


specifications in the calling program. After the REPLACING phrase is executed, the 
source listing contains the original library text. The source listing does not contain the: 
results of the REPLACING phrase. 


Pseudotext is a sequence of text-words or comments bounded by two consecutive equal 
signs (= =). This sequence specifically excludes partial words. Allowable separators 

in the pseudotext are commas (,), semicolons (;), and spaces; a nonnumeric literal can 
contain quotation marks ("). Pseudotext-1 must not be null and cannot consist solely of 
Spaces or comment lines. Pseudotext-2 can be null. 


Character strings within pseudotext-1 and pseudotext-2 can be continued. However, 
both characters of a pseudotext delimiter must be on the same line. 


Word-1 or word-2 can be any single COBOL word, including a COBOL reserved word. 


For purposes of matching, identifier-1, word-1, and literal-1 are treated as pseudotext 
containing only identifier-1, word-1, or literal-1, respectively. 


The comparison operation to determine text replacement occurs in the following 
manner: 


e Any separator comma, semicolon, or space preceding the leftmost library text-word 
' is copied into the source program. Starting with the leftmost library text-word and 
the first pseudotext-1, identifier-1, word-1, or literal-1 specified in the REPLACING 
phrase, the entire REPLACING phrase operand that precedes the reserved word BY 
is compared to an equivalent number of contiguous library text-words. 


e  Pseudotext-1, identifier-1, word-1, or literal-1 match the library text only if the - 


ordered sequence of text-words that forms pseudotext-1, identifier-1, word-1, 
or literal-1 is equal, character for character, to the ordered sequence of library 
text-words. 


For purposes of matching, each occurrence of a separator comma or semicolon 

in pseudotext-1 or in the library text is considered to be a single space, except 
when pseudotext-1 consists solely of either a comma or a semicolon. In that case, 
pseudotext-1 participates in the match as a text-word. Each sequence of one or 
more space separators is considered to be a single space. 


e Ifno match occurs, the comparison is repeated with each successive pseudotext-1, 
identifier-1, word-1, or literal-1, if any, in the REPLACING parene until either a 
match is found or no REPLACING operand remains. 
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When all REPLACING phrase operands have been compared and no match has 
occurred, the leftmost library text-word is copied into the source program. The next 
successive library text-word is then considered to be the leftmost library text-word, 
and the comparison cycle starts again with the first pseudotext-1, identifier-1, 
word-1, or literal-1 specified in the REPLACING phrase. 


Whenever a match occurs between pseudotext-1, identifier-1, word-1, or literal-1 and 
the library text, the corresponding pseudotext-2, identifier-2, word-2, or literal-2 

is placed in the source program. The library text-word immediately following 

the rightmost text-word that participates in the match is then considered to be 

the leftmost library text-word. The comparison cycle starts again with the first 
pseudotext-1, identifier-1, word-1, or literal-1 specified in the REPLACING phrase. 


e The comparison operation continues until the rightmost text-word in the library 
text has either participated in a match or has been considered as a leftmost library 
text-word and participated in a complete comparison cycle. 


For matching, a comment line occurring in the library text and in pseudotext-1 is 
interpreted as a single space. Comment lines appearing in pseudotext-2 and library text 
are copied into the source program unchanged. 


Debugging lines are permitted in library text and pseudotext-2. Debugging lines are not 
permitted in pseudotext-1; text-words in a debugging line participate in the matching 
rules as if the letter D did not appear in the indicator area. If a COPY statement 

is specified on a debugging line, the text that results from the processing of the 

COPY statement appears as if it were specified on debugging lines, with the following 
exception: comment lines in library text appear as comment lines in the resultant source 
program. 


After replacement, text-words are placed in the source program for compilation 
according to the rules for reference format. 


semicolon (;) (Unisys Extension) 


The semicolon (;) that follows the ending period can be used to control the behavior of 
compiler control records (CCRs) and the format of listings. This semicolon should always 
be separated from the ending period of the COPY statement by at least one space. 


If a CCR immediately follows a COPY statement, the compiler option changes might 
occur before the compiler processes the included source information. This situation can 
be avoided by using the semicolon after the ending period. The semicolon ensures that 
the compiler processes the included source information before the option changes. 


When a compilation listing is produced, a comment immediately following'a COPY 
statement might be printed after the COPY statement but before the information 
included as a result of the COPY statement. Ifa semicolon is placed after the ending 
period but before the comment entry, the comment is printed after the included source 
information. : 


Use the optional semicolon with caution. In some cases, the compiler may recognize the 


optional semicolon. In other cases, the compiler may prohibit the use of the semicolon. 
In the latter cases, the semicolon may not produce the desired listing format and even 
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produce syntax errors. In such cases, use the semicolon as a tool in determining whether 
errors can be eliminated. 


In general, the semicolon can produce undesirable listing formats in the following cases: 


e Multiple COPY statements follow each other with no intervening syntax. 
e COPY statements have semicolons. 


e The last element in the library that is the subject of a COPY statement is a 
PICTURE string that ends with one or more 9s followed by a period terminating the 
DATA declaration. 


‘If the last statement of a COBOL74 program is a COPY statement, do not use a 


semicolon with that statement. The last syntax element of a COBOL74 program 
must always be a period that terminates the last statement or paragraph-name of the 
program. 


Examples 


The following examples represent different ways of incorporating (SYSTEM)A/B/C ON 
SYSPACK into the program. 


COPY "(SYSTEM)A/B/C ON SYSPACK.". 
COPY C OF B OF A OF (SYSTEM) ON SYSPACK. 


DELETE 


The DELETE statement logically removes a record from a mass-storage file. 


The general format of this statement is as follows: 


DELETE file-name RECORD [ ; INVALID KEY imperative-statement | 
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Explanation of Format 


The file-name must be a relative or an indexed file. 


The imperative-statement can be the NEXT SENTENCE phrase. 


For a file in the sequential access mode, the last I/O statement executed prior to 
execution of the DELETE statement must have been a successfully executed READ 
statement. The record accessed by the READ statement is deleted from the file. 


For a file in random or dynamic access mode, the record to be deleted is identified by the 


contents of the relative or prime record key data item associated with the file-name. If 
the file does not contain the record specified by the key, an Invalid Key condition exists. 
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The file must be open in the I-O mode when this statement is executed. 


After the successful execution of a DELETE statement, the identified record that is 
logically removed from the file can no longer be accessed. 


The execution of a DELETE statement does not affect the contents of the record area 
associated with the file-name, nor does it affect the current record pointer. 


However, the execution of the DELETE statement causes the BPERORIANE FILE 
STATUS data item, if any, to be updated. 


DETACH (Unisys Extension) 


The DETACH statement dissociates a procedure from a task item or an EVENT item. 


The general format of this statement is as follows: 


DETACH identifier-1 [ , identifier-2 ]... 


Explanation of Format 


Identifiers used in this statement must be defined as either elementary task items or. 
section-names in the DECLARATIVES SECTION with a USE AS INTERRUPT clause. 


If a task item is being detached, it must previously have been implicitly attached by 
the execution of a CALL, PROCESS, or RUN statement. The successful execution of 
a statement terminates the task that was attached to the task-identifier of the task 
and was running, because the STATUS attribute was set to TERMINATED. After 
execution of the DETACH statement, the task-identifier should be tested for STATUS 
of TERMINATED prior to the next use of that task-identifier ina CALL, PROCESS, 
or RUN statement, because execution of the program that contained the DETACH 
statement continues asynchronously while the detachment is performed. 


Execution of a DETACH section-name statement severs the association of that interrupt 
procedure with its currently attached event. Detaching an interrupt procedure that is 
not attached to an event does not cause an error. Executions of the interrupt procedure, 
which might have been queued at the time of the detachment, do not occur. 


The Allowed or Disallowed condition of the interrupt procedure is not changed by a 


DETACH statement. If the interrupt is subsequently attached, the condition is the same 
as it was before the DETACH statement. 
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See Also 


e For information about executing an interrupt procedure that has been attached to an 
EVENT item, refer to “ALLOW (Unisys Extension)” earlier in this section. 


e For information about associating an interrupt procedure with an EVENT item, 
refer to “ATTACH (Unisys Extension)” earlier in this section. 


e For information about preventing execution of an interrupt procedure that has been 
attached to an event, refer to “DISALLOW” earlier in this section. 


e For information about specifying procedures for I/O exception handling, refer to 
“USE” later in this section. 


DISALLOW 


The DISALLOW statement prevents execution of an interrupt procedure that has been 
attached to an event. 


The DISALLOW statement has the following two formats: 


Format Explanation 
1 Enables you to specify the interrupt procedures that are not to be executed 
2 Causes a General Disallow Interrupt condition 
Format 1 


DISALLOW section-name-1 [ , section-name-2 ]... 


Explanation of Format 1 


The section-names specify the interrupt procedures that are not to be executed 
when their attached events occur. The sections named must be defined in the 
DECLARATIVES SECTION with the USE AS INTERRUPT clause in their headers. 
The section-names must be allowed when the DISALLOW statement is executed. 


Format 2 


DISALLOW INTERRUPT 


Explanation of Format 2 


The DISALLOW INTERRUPT statement causes a General Disallow Interrupt condition. 
During the time the General Disallow Interrupt condition is in effect, execution of an 
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interrupt procedure that is attached to an event is queued when the event is caused. 
Later execution of an ALLOW INTERRUPT statement immediately executes any 
queued procedures that are not currently disallowed because of a specific DISALLOW 
section-name statement. 


General Rules 


After execution of a DISALLOW section-name statement, the system queues executions 
of the specified interrupt procedures because of the events being caused. Their 
execution can later be caused by a corresponding ALLOW section-name statement unless 
a General Disallow Interrupt condition is in effect. The current state of the General 
Disallow Interrupt condition does not affect whether an interrupt is specifically allowed 
or disallowed. 


See Also 
e For information about executing an interrupt procedure that has been attached to an 
EVENT item, refer to “ALLOW (Unisys Extension)” earlier in this section. 


e For information about associating an interrupt procedure with an EVENT item, 
refer to “ATTACH (Unisys Extension)” earlier in this section. 


e For information about preventing execution of an interrupt procedure that has been 
attached to an event, refer to “DISALLOW?” earlier in this section. 


e For information about dissociating a procedure from a task item or an EVENT item, 
refer to “DETACH (Unisys Extension)” earlier in this section. 


e For information about specifying procedures for I/O exception handling, refer to 
“USE” later in this section. ; 


DISPLAY 


The DISPLAY statement transfers data to an operator display terminal (ODT). 


The general format of this statement is as follows: 


DISPLAY ae ; identifier-2 


literal-1 , literal-2 


| .../ UPON mnemonic-name | 


Explanation of Format 


The DISPLAY statement causes the contents of each operand to be transferred in the 
order listed. 


If a figurative constant is specified as one of the operands, only a single occurrence of the 
figurative constant is displayed. 
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Each literal can be any figurative constant except ALL. 


When a DISPLAY statement contains more than one operand, the size of the sending | 
item is the sum of the sizes associated with the operands, and the values of the operands 
are transferred in the sequence in which the operands are encountered. In a Unisys 
extension, if the data transferred does not fit on one line, carriage returns and line feeds 
are supplied so that the data is extended to other lines of print. 


If the UPON phrase is not used, the device used is the ODT. 


The mnemonic-name is associated with a hardware device in the SPECIAL-NAMES 
paragraph in the ENVIRONMENT DIVISION and must be associated with the 
hardware-name ODT. 


The operating system, when processing a DISPLAY statement, stops at the first null 
(hex 00). The operating system initializes data areas to all nulls. Therefore, if a FILLER 
item without a VALUE clause is present in a group item being displayed, the display 
ends with this item. (This is a Unisys extension.) . 


DIVIDE 


_ The DIVIDE statement divides one numeric data item into others and sets the values of 
data items equal to the quotient and remainder. 


The DIVIDE statement has the following five formats: 
Format Explanation 


1 The DIVIDE...INTO format enables you to divide a numeric operand into another 
numeric operand and to store the result in the second operand. 


2 The DIVIDE...INTO...GIVING format enables you to divide a numeric operand into 
another numeric operand and to specify a place to store the result. 


3 The DIVIDE...BY...GIVING format enables you to divide a numeric operand by | 
another numeric operand and to specify a place to store the result. 


4 The DIVIDE...INTO...GIVING...REMAINDER format enables you to divide a 
numeric operand into another numeric operand and to specify a place to store the 
result and the remainder. 


5 The DIVIDE...BY...GIVING...REMAINDER format enables you to divide a numeric 
operand by another numeric operand and to specify a place to store the result. 
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Format 1 


DIVIDE 


aera 


; } INTO identifier-2 [ ROUNDED | 
literal-1 


[ identifier-3 [ ROUNDED ] ] ... 


[ ; ON SIZE ERROR imperative-statement | 


Explanation of Format 1 

When Format 1 is used, the value of identifier-1 or literal-1 is divided into the value of 
identifier-2. The value of the dividend (identifier-2) is replaced by this quotient; the 
process is then repeated for identifier-1 or literal-1 and identifier-3, and so on. 

Each identifier must refer to an elementary numeric item. 


Each literal must be a numeric literal. 


The imperative-statement can be the NEXT SENTENCE phrase. 


Format 2 


DIVIDE oe} oe eared 


. ; } GIVING identifier-3 [ ROUNDED | 
literal-1 literal-2 


[ , identifier-4 [ ROUNDED ] | ... 


[ ; ON SIZE ERROR imperative-statement | 


Explanation of Format 2 


When Format 2 is used, the value of identifier-1 or literal-1 is divided into identifier-2 or 
literal-2, and the result is stored in identifier-3, identifier-4, and so on. ; 


Each identifier must refer to an elementary numeric item, except that any identifier 


associated with the GIVING phrase must refer to either an elementary numeric item or 
an elementary numeric-edited item. 
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Each literal must be a numeric literal. 


The imperative-statement can be the NEXT SENTENCE phrase. 


Format 3 


B 


literal-2 


E sarees 


| GIVING identifier-3 [ ROUNDED | 
literal-1 


[ , identifier-4 [ ROUNDED ] ]... 


[ ; ON SIZE ERROR imperative-statement | 


Explanation of Format 3 


When Format 3 is used, the value of identifier-1 or literal-1 is divided by the value of 
identifier-2 or literal-2, and the result is stored in identifier-3, identifier-4, and so on. 


Each identifier must refer to an elementary numeric item, except that any identifier 
associated with the GIVING phrase must refer to either an elementary numeric item or 
an elementary numeric-edited item. 


Each literal must be a numeric literal. 


The imperative-statement can be the NEXT SENTENCE phrase. 


Format 4 


DIVIDE vaca, N eae 


: ; } GIVING identifier-3 [ ROUNDED | 
literal-1 literal-2 


REMAINDER identifier-4 [ ; ON SIZE ERROR imperative-statement | 
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Format 5 


DIVIDE B 


ee 1 


air 


; } GIVING identifier-3 | ROUNDED | 
literal-2 


literal-1 


REMAINDER identifier-4 [ ; ON SIZE ERROR imperative-statement | 


Explanation of Format 4 and 5 


Formats 4 and 5 are used when a remainder from the division operation is desired, 
namely identifier-4. The remainder in COBOL is defined as the result of subtracting the 
product of the quotient (identifier-3) and the divisor from the dividend. If identifier-3 

is defined as a numeric-edited item, the quotient used to calculate the remainder is an 
intermediate field that contains the unedited quotient. If the word ROUNDED is used, 
the quotient used to calculate the remainder is an intermediate field that contains the 
quotient of the DIVIDE statement in truncated rather than rounded form. 


In Formats 4 and 5, the accuracy of the REMAINDER data item (identifier-4) is defined 

by the preceding calculation. Appropriate decimal alignment and truncation (not 

rounding) are performed for the content of the data item referenced by identifier-4, as 

needed. 

Each identifier must refer to an elementary numeric item, except that any identifier 

associated with the GIVING or REMAINDER phrase must refer to either an elementary 

numeric item or an elementary numeric-edited item. 

Each literal must be a numeric literal. 

The imperative-statement can be the NEXT SEN TENCE phrase. 

When the ON SIZE ERROR phrase is used in Formats 4 and 5, the following rules apply: 
_@ Ifthe Size Error condition occurs on the quotient, no remainder calculation is 


meaningful. Thus, the contents of the data items referenced by both identifier-3 and 
identifier-4 remain unchanged. 


e Ifthe Size Error condition occurs on the remainder, the contents of the data item 
referenced by identifier-4 remain unchanged. 


General Rules 
The following information applies to all formats. 


When a sending item and a receiving item in the same DIVIDE statement share a part, 
but not all, of their storage areas, the result of the statement execution is undefined. 
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See Also 


e Fora description of the features common to the arithmetic statements, refer 
to “Common Rules for Arithmetic Statements” in Section 8, “PROCEDURE 
DIVISION Concepts.” 


e For information on producing multiple results with one arithmetic statement, refer 
to “Calculating Multiple Results with One Arithmetic Statement” in Section 8, 
“PROCEDURE DIVISION Concepts.” 


e For information about rounding of arithmetic result fields, refer to “ROUNDED. 
Phrase” in Section 8, “PROCEDURE DIVISION Concepts.” 


e For information on Size Error conditions, refer to “ SIZE ERROR Phrase” in 
Section 8, “PROCEDURE DIVISION Concepts.” 


EXECUTE (Unisys Extension) 
The EXECUTE statement is Sarnonius with the RUN statement. 


See Also 


For information about this statement, refer to “RUN (Unisys Extension)” later in this 
section. 


EXIT 


The EXIT statement allows you to end a series, section of paragraphs, exit from a bound 
procedure or called program, or bypass statements. 


The EXIT statement has the following four formats: | ; 
Format Explanation | 
1 Ends a series of sections or paragraphs referenced by a PERFORM statement 
2 Enables you to exit from a bound procedure 
3 Enables you to exit from a called program 
4 Enables you to bypass statements 


Format 1 


EXIT . 
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Explanation of Format 1 

The EXIT statement provides a common method for documenting the logical endpoint 
for a series of sections or paragraphs that can be executed under the control of a 
PERFORM statement. 


The EXIT statement must appear in a sentence by itself and must be the only sentence 
in the paragraph. 


A simple EXIT statement only assigns a procedure-name to a given point in a program 
and has no effect on execution of the program. 


Format 2 (Unisys Extension) 


EXIT PROCEDURE . 


Explanation of Format 2 


The EXIT PROCEDURE statement provides a mechanism for returning from a bound 
procedure. 


Ifa Format 2 statement appears in a consecutive sequence of imperative statements 
within a sentence, it must appear as the last statement in that sequence. If the program 
in which it appears is not a bound procedure, then the EXIT PROCEDURE statement is 
synonymous with the STOP RUN statement. 


The EXIT PROCEDURE statement should be used only for procedures compiled 

at level 3 or higher. If the procedure has been processed or called as a coroutine, 
end-of-task (EOT) occurs for that stack. If the procedure has been called as a procedure, 
normal exit routines transfer control back to the statement following the procedure 
invocation in the calling program. 


An implicit EXIT PROCEDURE statément is compiled for all procedures compiled at 


level 3 or higher. The EXIT PROCEDURE statement need not be used when it would be 
the final statement in the procedure. 


Format 3 (Unisys Extension) 


EXIT PROGRAM [ RETURN HERE ] . 
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Explanation of Format 3 


An EXIT PROGRAM statement is designed to be used to return from a program that is 
under control of a CALL statement. 


If an EXIT PROGRAM statement is executed while a program is under control of a 
tasking CALL statement, then control returns to the statement following the CALL 
statement in the calling program. If a subsequent CONTINUE statement is executed 
for the same program, control passes to the first logically executable statement in the 
called program. 


‘The EXIT PROGRAM statement and RETURN HERE option provide a mechanism for 


passing control between a dependent task and its initiating program. 

If a Format 3 statement without the RETURN HERE phrase appears in a consecutive 
sequence of imperative statements within a sentence, it must be the last statement in 
that sequence. 

An EXIT PROGRAM RETURN HERE statement cannot appear in a bound procedure. 
When the EXIT PROGRAM RETURN HERE statement is used and a CONTINUE 


statement is executed on the same program, control passes to the statement 
immediately following the EXIT statement. 


Format 4 (Unisys Extension) 


EXIT PERFORM. 
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Explanation of Format 4 


The EXIT PERFORM statement provides a way to bypass the petneincer of a 
PERFORM statement range. 


If the program is under control of a PERFORM statement when the EXIT PERFORM 
statement is encountered, any remaining statements in the PERFORM statement range 


are bypassed. If an EXIT PERFORM statement is executed when no PERFORM 
statement is active, control passes to the next statement. 


See Also 


For information on returning control from a library to a calling program, refer to 
“Exiting a Library” in Section 15, “Libraries.” 
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GO TO 


The GO TO statement explicitly transfers control to another procedure. 


The GO TO statement has the following two formats: 


Format Explanation 

1 The GO TO format transfers control from one part of the PROCEDURE DIVISION 
to another. 

2 The GO TO...DEPENDING ON format transfers control from one part of the 
PROCEDURE DIVISION to another, depending on the value of a specified integer 
identifier. 

Format 1 


GO TO | procedure-name-1 | 


Explanation of Format 1 


When a GO TO statement executes, control transfers to procedure-name-1 or to another 
procedure-name if the GO TO statement has been modified by an ALTER statement. 


If procedure-name-1 is not specified, an ALTER statement referring to this GO TO 
‘statement must be executed prior to the execution of this GO TO statement. Otherwise, 


the program terminates abnormally. 


When a paragraph is referenced by an ALTER statement, that paragraph can consist of 
only a paragraph header followed by a Format 1 GO TO statement. 


A Format 1 GO TO statement without procedure-name-1 can appear only ina 
single-statement paragraph. : 


Ifa GO TO statement appears ina consecutive sequence of imperative statements 
within a sentence, it must be the last statement in that sequence. 


Format 2 


GO TO procedure-name-1 , procedure-name-2 [ , procedure-name-n ]... 


DEPENDING ON identifier 
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IF 


Explanation of Format 2 


When a GO TO statement executes, control transfers to procedure-name-1, 
procedure-name-2, and so on, depending on whether the value of the identifier is 1, 2, or 
another integer value. If the value of the identifier is anything other than a positive or 
unsigned integer, no transfer occurs and control passes to the next statement. 


The identifier is the name of an elementary numeric item that describes an integer. It 
cannot be a formula or another expression. 


The IF statement evaluates a condition. The subsequent action of the object program 
depends on whether the value of the condition is TRUE or FALSE. 


The general format of this statement is as follows: 


NEXT SENTENCE NEXT SENTENCE 


IF condition; THEN nee \ E ELSE eee -2 ! 
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Explanation of Format 


Statement-1 and statement-2 represent either an imperative statement or a conditional 
statement; either type of statement can be followed by a conditional statement. 


When an IF statement is executed, the following transfers of control occur: 


e Ifthe condition is TRUE, statement-1 is executed if specified. If statement-1 
contains a procedure branching statement or conditional statement, control is 
explicitly transferred under the rules of that statement. If statement-1 does not 
contain a procedure branching or conditional statement, the specified ELSE phrase 
is ignored and control passes to the next executable sentence. | 


e Ifthe condition is TRUE and the NEXT SENTENCE phrase is specified instead of 
statement-1, the specified ELSE phrase is ignored and control passes to the next 
executable sentence. 


e Ifthe condition is FALSE, statement-1 or its alternative, NEXT SENTENCE, is 
ignored; statement-2, if specified, is executed. If statement-2 contains a procedure 
branching or conditional statement, control is explicitly transferred under the 
rules of that statement. If statement-2 does not contain a procedure branching or 
conditional statement, control passes to the next executable sentence. If the ELSE 
statement-2 phrase is not specified, statement-1 is ignored and control passes to the 
next executable sentence. 


e Ifthe condition is FALSE and the ELSE NEXT SENTENCE phrase is specified, 
_ gtatement-1 is ignored, if specified, and control passes to the next executable 
sentence. 
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Statement-1, statement-2, or both can each contain an IF statement. In this case, the IF 
statement is nested. ; 


IF statements within IF statements can be considered paired IF and ELSE 
combinations, proceeding from left to right. Thus, any ELSE statement encountered 


applies to the immediately-preceding IF statement that has not been already paired with | 
an ELSE statement. 


See Also 


For information about conditions, refer to “Conditional Statements and Sentences” in 
Section 8, “PROCEDURE DIVISION Concepts.” 


INSPECT 


The INSPECT statement tallies, replaces, or tallies and replaces occurrences of single 
characters or groups of characters in a data item. 


When a sending item and a receiving item in the same INSPECT statement share a 
part, but not all, of their storage areas, the result of the execution of the statement is 
undefined. — 


The INSPECT statement has the following three formats: 


Format Explanation 
1 The INSPECT...TALLYING format tallies single characters or groups of characters. 
2 The INSPECT...REPLACING format replaces single characters or groups of 
characters. 
3 The INSPECT...TALLYING and REPLACING format tallies and replaces single 


characters or groups of characters; this format combines Formats 1 and 2. 


Format 1 


INSPECT identifier-1 TALLYING 


, identifier-2 


er \ our} 
; LEADING } l(literal-1 
FOR CHARACTERS 

| ore, INITIAL ion 


AFTER literal-2 
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Explanation of Format 1 
Note: Unpredictable results can occur if identifier-1 is longer than 4095 
bytes or if any one of identifier-3 through identifier-n is longer than 


255 bytes. This is a permanent restriction. Avoid programs that 
violate it. 


identifier-1 - 


Identifier-1 must reference either a group item or any category of elementary data item 
described implicitly or explicitly as USAGE IS DISPLAY. 


identifier-2 
Identifier-2 must reference an elementary numeric data item. 


The contents of the data item referenced by identifier-2 are not initialized by execution 
of the INSPECT statement. 


ALL 


If the ALL phrase is specified, the contents of the data item referenced by identifier-2 
are incremented by one for each occurrence of literal-1 matched within the contents of 
the data item referenced by identifier-1. 


LEADING 


If the LEADING phrase is specified, the contents of the data item referenced by 
identifier-2 are incremented by one for each contiguous occurrence of literal-1 matched 
within the contents of the data item referenced by identifier-1. The leftmost such 
occurrence must be at the point where comparison began in the first comparison cycle in 
which literal-1 was eligible to participate. . 


CHARACTERS 


If the CHARACTERS phrase is specified, the contents of the data item referenced by 
identifier-2 are incremented by one for each character matched within the contents of 


the data item referenced by identifier-1. 


identifier-3 


Identifier-3 through identifier-n must reference elementary alphabetic, alphanumeric, or | 
numeric items described implicitly or explicitly as USAGE IS DISPLAY. 


literal-1, literal-2 


If either literal-1 or literal-2 is a figurative constant, the figurative constant refers to an 
implicit, one-character data item. 
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Each literal must be nonnumeric and can be any figurative constant except ALL. 


See Also 


For information on the BEFORE and AFTER phrases, see “Establishing Boundaries for 
the BEFORE or AFTER Phrase” later in this section. 


Format 2 | 


INSPECT identifier-1 REPLACING 


CHARACTERS BY { identifier-6 i 


literal-4 
BEFORE { identifier-7 
————— _\ INITIAL 
| AFTER } 7 eee } 
wa {ier (str 
on er =, 
‘ LEADING | { BEFORE 


FIRST AFTER 


} INITIAL { identifier-7 } | 


literal-5 


Explanation of Format 2 
Note: Unpredictable results can occur if identifier-1 is longer than 4095 
bytes or if any one of identifier-3 through identifier-n is longer than 


255 bytes. This is a permanent restriction. Avoid programs that 
violate it. 


identifier-1 


Identifier-1 must reference either a group item or any category of elementary data item — 
described implicitly or explicitly as USAGE IS DISPLAY. 


identifier-5 


Identifier-5 through identifier-n must reference elementary alphabetic, alphanumeric, or 
numeric items described implicitly or explicitly as USAGE IS DISPLAY. 


CHARACTERS 


When the CHARACTERS phrase is used, literal-4, literal-5, or the size of the data item 
referenced by identifier-6 or identifier-7 must be 1 character long. Each character 
matched in the contents of the data item referenced by identifier-1 is replaced by 
literal-4. . 
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literal-4 and identifier-6 
The size of the data referenced by literal-4 or identifier-6 must equal the size of the data 
referenced by literal-3 or identifier-5. When a figurative constant is used as literal-4, the 


size of the figurative constant equals the size of literal-3 or the size of the data item 
referenced by identifier-5. 


literal-3 


When a figurative constant is used as literal-3, the data referenced by literal-4 or 
identifier-6 must be 1 character long. 


Each literal must be nonnumeric and can be any figurative constant except ALL. 


ALL 


When the adjective ALL is specified, each occurrence of literal-3 matched in the contents 
of the data item referenced by identifier-1 is replaced by literal-4. 


LEADING 
When the adjective LEADING is specified, each contiguous occurrence of literal-3 
matched in the contents of the data item referenced by identifier-1 is replaced by 


literal-4, provided that the leftmost occurrence is at the point where comparison began in 
the first comparison cycle in which literal-3 was eligible to participate. 


FIRST 


When the adjective FIRST is specified, the leftmost occurrence of literal-3 matched in 
the contents of the data item referenced by identifier-1 is replaced by literal-4. 


BY 


The required words ALL, LEADING, and FIRST are adjectives that apply to each 
_ succeeding BY phrase until the next adjective appears. 


Format 3 


A Format 3 INSPECT statement is interpreted and executed as if two successive 
INSPECT statements specifying the same identifier-1 were written. One statement is a 
Format 1 statement with TALLYING phrases identical to those specified in the Format 
3 statement; the other statement is a Format 2 statement with REPLACING phrases 


identical to those specified in the Format 3 statement. The rules for matching and 


counting apply to the Format 1 statement; the rules for matching and replacing apply to 
the Format 2 statement. 
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INSPECT identifier-1 TALLYING 


, identifier-2. 
| en \ je: 
{ LEADING J l\literal-1 ; 
FOR CHARACTERS 


| ane 


identifier-1 
AFTER } INITIAL { \ 


literal-2 
REPLACING 


CHARACTERS BY { 


BEFORE 
AFTER 


identifier-6 } 
literal-4 


} INITIAL { 


identifier-7 } 
literal-5 | 
AE | ; { identifier-5 } BY { identifier-6 } 
literal-3 literal-4 
,< LEADING : ' 
| FIRST | { BEFORE } INITIAL { identifier-7 } 
oe AFTER literal-5 


Explanation of Format 3 

Note: Unpredictable results can occur if identifier-1 is longer than 4095 
bytes or if any one of identifier-3 through identifier-n is longer than 
255 bytes. This is a permanent restriction. Avoid programs that 
violate it. j 


Identifier-1 must reference either a group item or any category of elementary data item 
described implicitly or explicitly as USAGE IS DISPLAY. 


Identifier-2 must reference an elementary numeric data item. 


Identifier-3 through identifier-n must reference elementary alphabetic, alphanumeric, or 
numeric items described implicitly or explicitly as USAGE IS DISPLAY. 


If either literal-1 or literal-2 is a figurative constant, the figurative constant refers to an 
implicit, 1-character data item. 


The size of the data referenced by identifier-6 or literal-4 must equal the size of the data 
referenced by identifier-5 or literal-38. When a figurative constant is used as literal-4, the 
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size of the figurative constant equals the size of literal-3 or the size of the data item 
referenced by identifier-5. 


When the CHARACTERS phrase is used, literal-4, literal-5, or the size of the data item 
referenced by identifier-6 or identifier-7 must be 1-character long. 


When a figurative constant is used as literal-3, the data referenced by literal-4 or 
identifier-6 must be one character long. 


Each literal must be nonnumeric and can be any figurative constant except ALL. 


Note that with undigit literals each pair of hexadecimal digits corresponds to one 8-bit 
character. (Undigit literals are a Unisys extension.) 


Inspection 


The process of inspection has the following three stages: 


e The comparison cycle 

e The mechanism for tallying, replacing, or both tallying and replacing 

e The establishment of boundaries for the BEFORE or AFTER phrase 
Inspection begins at the leftmost character position of the data item referenced by 


identifier-1, regardless of its class, and proceeds from left to right to the rightmost 
character position. 


Comparison Cycle 


9-58 


All references to identifier-1 also apply to identifier-3, identifier-4, identifier-5, 
identifier-6, and identifier-7. 


All references to literal-1, literal-2, literal-3, literal-4, and literal-5 also apply to the 
contents of the data item referenced by identifier-3, identifier-4, identifier-5, identifier-6, 
and identifier-7, respectively. 


The INSPECT statement treats the contents of the data item referenced by identifier-1 
as follows: 


e If identifier-1 is described as alphanumeric, the INSPECT statement treats the 
contents of each such identifier as a character string. 


e If identifier-1 is described as alphanumeric-edited, numeric-edited, or unsigned 
_ numeric, the INSPECT statement inspects the data item as if it were redefined 
as alphanumeric and as if the INSPECT statement were written to reference the 
redefined data item. 


e Ifidentifier-1 is described as signed numeric, the INSPECT statement inspects the 
data item as if it had been moved to an unsigned numeric data item of the same 
length, and as if the INSPECT statement were written to reference the redefined 
data item. 
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Tallying and Replacing 


During inspection of the contents of the data item referenced by identifier-1, each 
properly matched occurrence of literal-1 is tallied (Formats 1 and 3), and/or each 
properly matched occurrence of literal-3 is replaced by literal-4 (Formats 2 and 3). 


The comparison cycle, which determines the occurrences of literal-1 to be tallied and the 
occurrences of literal-3 to be replaced, occurs as follows: 


The operands of the TALLYING and REPLACING phrases are considered in the 
order in which they are specified in the INSPECT statement from left to right. The 
first literal-1/literal-3 is compared with an equal number of contiguous characters, 
starting with the leftmost character position in the data item referenced by 
identifier-1. Literal-1/literal-3 and the portion of the contents of identifier-1 match 
only if they are equal on a character-for-character basis. 


If no match occurs in the comparison of the first literal-1/literal-3, the comparison is 
repeated with each successive literal-1/literal-3, if any, until either a match is found 
or no subsequent literal-1/literal-3 remains. When no subsequent literal-1/literal-3 
remains, the character position in identifier-1 immediately to the right of the 
leftmost character position in the last comparison cycle is considered as the 
leftmost character position, and the comparison cycle begins again with the first 
literal-1/literal-3. . 


Whenever a match occurs, tallying, replacing, or both occurs. The character position 
in identifier-1 immediately to the right of the rightmost character position that 
participated in the match is now considered to be the leftmost character position of 
the data item referenced by identifier-1, and the comparison cycle starts again with 
the first literal-1/literal-3. 


. The comparison operation continues until the rightmost character position of 


identifier-1 has participated in a match or has been considered as the leftmost 
character position. When this situation occurs, inspection is terminated. 


If the CHARACTERS phrase is specified, an implied, 1-character operand 
participates in the cycle previously described , except that no comparison with the 
contents of identifier-1 takes place. This implied character is always considered 
to match the leftmost character of the contents of the data item referenced by 
identifier-1. . 


See Also 


For a description of move operations, refer to “MOVE” later in this section. 
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Establishing Boundaries for the BEFORE or AFTER Phrase 


The comparison operation defined earlier is performed by the BEFORE and AFTER 
phrases as follows: 


e Ifthe BEFORE or AFTER phrase is not specified, literal-1/literal-3 or the implied 
operand of the CHARACTERS phrase participates in the comparison cycle. 


e Ifthe BEFORE phrase is specified, literal-1/literal-3 or the implied operand of the 
CHARACTERS phrase participates only in comparison cycles that involve the 
contents of identifier-1 from its leftmost character position up to, but not including, 
the first occurrence of literal-2/literal-5 within the contents of identifier-1. The 
position of the first occurrence is determined before the beginning of the first cycle of 
the comparison operation. 


If, on any comparison cycle, literal-1/literal-3 or the implied operand of the 
CHARACTERS phrase is not eligible to participate, this variable does not match 
the contents of identifier-1. If literal-2/literal-5 does not occur within the contents 
of identifier-1, then literal-1/literal-3 or the implied operand of the CHARACTERS 
phrase participates in the comparison operation as if the BEFORE phrase had not 
been specified. 


e Ifthe AFTER phrase is specified, literal-1/literal-3.or the implied operand of the 
CHARACTERS phrase can participate only in comparison cycles that involve the 
contents of identifier-1 beginning with the character position immediately to the 
right of the rightmost character position of the first occurrence of literal-2/literal-5 
within the contents of identifier-1. The position of this first occurrence is 
determined before the beginning of the first cycle of the comparison operation. 


If, on any comparison cycle, literal-1/literal-3 or the implied operand of the 
CHARACTERS phrase is not eligible to participate, it is considered not to match the 
contents of identifier-1. If literal-2/literal-5 does not occur within the contents of 
identifier-1, literal-1/literal-3 or the implied operand of the CHARACTERS phrase is 
never eligible to participate in the comparison operation. 


Examples of the INSPECT Statement 


Examples 9-11 through 9-18 illustrate the use of the INSPECT statement. 


Example 9-11 counts the number of leading zeros in the specified word. 


INSPECT word TALLYING count FOR LEADING "@". 


Word Count 
00009876 4 
12345 — 0 


Example 9-11. Coding an INSPECT TALLYING Statement with LEADING Option 
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Example 9-12 counts the number of characters before the first Z character. 


INSPECT word TALLYING count FOR CHARACTERS BEFORE INITIAL "Z". 


Word Count 
ALPHA 5. 
ABCDEFZ 6 


Example 9-12. Coding an INSPECT TALLYING Statement with BEFORE INITIAL 
| Option 


Example 9-13 counts the number of characters that occur before the first A character 
and counts the number of A characters followed immediately by an L character. 


INSPECT word TALLYING count FOR LEADING "L" BEFORE INITIAL 
"A", count-1 FOR LEADING "A" BEFORE INITIAL "L". 


Word First Count Second Count 
LARGE 1 0 
ANALYST | 0 


1 


Example 9-13. Coding an INSPECT TALLYING Statement with LEADING BEFORE 
Option 


Example 9-14 counts the number of L letters, and replaces an A with an E if the A 
_ occurs after the first L. 


INSPECT word TALLYING count FOR ALL "L", REPLACING LEADING 
"A" BY "E" AFTER INITIAL "L". 


Word Before Count Word After 
DOLLAR 2 DOLLAR | 
SALAMI 1 SALEMI 
LATTER > 1 LETTER 
Example 9-14. Coding an INSPECT TALLYING Statement with FOR ALL REPLACING 
Option 


Example 9-15 replaces all occurrences of the character A with the character G until all 
occurrences of the character X are inspected. 


INSPECT word REPLACING ALL "A" BY "G" BEFORE INITIAL "X". 


Word Before — Word After 
ARXAX GRXAX 
'HANDAX HGNDGX 


Example 9-15. Coding an INSPECT REPLACING ALL Statement with BEFORE 
INITIAL Option . 


8600 0296-000 9-61 


PROCEDURE DIVISION Statements 


Example 9~16 counts the number of characters after the first J character, and replaces 
all occurrences of the letter A by the letter B. 


INSPECT word TALLYING count FOR CHARACTERS AFTER INITIAL "J" 
REPLACING ALL "A" BY "B". 


Before Count — Word After 
ADJECTIVE 6 - BDJECTIVE 
JACK 3 JBCK 
JUJMAB 5 JUJMBB 


Example 9-16. Coding an INSPECT TALLYING REPLACING Statement 
Example 9-17 replaces X with Y, B with Z, “ind W with Q for all character after the first 
R character. 


INSPECT word REPLACING ALL "X" BY "Y", "B" BY "Z", "W" BY "Q" 
AFTER INITIAL "R". 


Word Before | Word After 
RXXBQMY_ : RYYZQQY 
YZACDWBR YZACDWZR 
RAWRXEB | ~ RAQRYEZ 


Example 9-17. Coding an INSPECT...REPLACING Statement with Literals 


Example 9-18 replaces all character with the letter B until an A character is inspected. 
INSPECT word REPLACING CHARACTERS BY "B" BEFORE INITIAL "A". 
Word Before Word After 
12XZABCD. BBBBABCD 
Example 9-18. Coding an INSPECT...REPLACING CHARACTERS Statement 


LOCK (Unisys Extension) 


The LOCK statement is used in an asynchronous processing environment. This 
statement enables one process to deny related processes access to a particular common 
storage area until the process has unlocked that area. It also permits a process to test a 
common storage area for a locked condition. 


The general format for this statement is as follows: 


LOCK ee 
event-identifier 


} | ; AT LOCKED { 


statement - 
NEXT SENTENCE 
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Explanation of Format 
Lock-identifiers must be declared with USAGE IS LOCK. 


Event-identifiers must be declared with USAGE IS EVENT or must be event-valued 
task attributes. 


If the AT LOCKED option is specified and the lock-name or event-name is already locked 
when the LOCK statement is executed, control passes to the statement following the 

AT LOCKED phrase. If AT LOCKED is not specified, the LOCK statement continues 

to try the operation until the LOCK has been successfully completed, that is, until the 
lock-name or event-name has been unlocked from other processes. 


The locking or unlocking of lock-identifier or event-identifier invokes the PROCURE 
and LIBERATE functions of the operating system and provides priority handling, thus 
_ eliminating contention problems. 


See Also 


For information about releasing restrictions on common resources, refer to “UNLOCK 
(Unisys Extension)” later in this section. 
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MERGE 


The MERGE statement combines two or more files by using a set of specified keys and, 
during this process, makes records available in merged order in an output procedure or 
an output file. 


The general format for this statement is as follows: 


PURGE 
MERGE file-name-1 


RUN ON nanon 
END 


ON { ASCENDING 


DESCENDING } KEY data-name-1 [ , data-name-2 J hg 


| ON { ASCENDING 


DESCENDING } KEY data-name-3 [ , data-name-4 ] .. ] 


[ COLLATING SEQUENCE IS alphabet-name ] 


LOCK LOCK | 
USING file-name-2 | PURGE | , file-name-3 | PURGE | 


RELEASE 


LOCK 
, file-name-4 PURGE | | ae 


RELEASE 


RELEASE 


‘ -( THROUGH 
OUTPUT PROCEDURE IS section-name-1 | { THRU 
SAVE 
LOCK 
GIVING file-name-5 | { RELEASE 
NO REWIND 


CRUNCH 


} section-name-2 
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Explanation of Format 


MERGE 


The MERGE statement merges all records contained on file-name-2, file-name-3, and 
file-name-4. The files referenced in the MERGE statement must not be open when the 
MERGE statement is executed; they are automatically opened and closed by the merge 
operation. The terminating function for all files is performed as if a CLOSE statement 
without optional phrases were executed for each file. 


MERGE statements can appear anywhere except in the DECLARATIVES SECTION 
_of the PROCEDURE DIVISION or in an INPUT PROCEDURE or an OUTPUT 
PROCEDURE associated with a SORT or MERGE statement. 


‘filenames 


File-name-1 must be described in a sort-merge file-description entry in the DATA 
DIVISION. File-name-2, file-name-3, file-name-4, and file-name-5 must be described 
in a file-description entry that is not a sort-merge file-description entry in the DATA 
DIVISION. The size of the largest logical records described for file-name-2, file-name-3, 
file-name-4, and file-name-5 must be paw to the size of the largest logical records | 

_ described for file-name-1. 


When the records in the files referenced by file-name-2, file-name-3, and so on are 

not ordered as described in the ASCENDING or DESCENDING KEY clauses, the 

merge operation takes place as previously described except that all improperly ordered 
data records are placed in the output file or returned to the OUTPUT PROCEDURE 
immediately after they are read from their respective input files. As a result, when such 
a condition exists, the output from the MERGE statement is not in a strict ASCENDING 
or DESCENDING KEY order. (This paragraph is a Unisys extension.) 


No more than one file-name from a multiple-file reel can appear in the MERGE 
statement. 


File-names must not be repeated in the MERGE statement. 


ON ERROR (Unisys Extension) 


The ON ERROR option enables you to have control over irrecoverable parity errors 
when an OUTPUT PROCEDURS is not present in a program. The PURGE option 
causes all records in a block containing an irrecoverable parity error to be dropped; 
processing is continued after a system message giving the relative position in the file 
of the bad block is printed. The RUN option causes the bad block to be used by the 
program and provides the same message as that defined for the PURGE option. The 
END option causes termination and is assumed if no option is specified. 
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ASCENDING or DESCENDING 


The data-names following the word KEY are listed from left to right in the MERGE 
statement in order of decreasing significance and without regard to their division into 
KEY phrases. In the format, data-name-1 is the major key, data-name-2 is the next most 
significant key, and so forth. 


e When the ASCENDING phrase is specified, the merged sequence is from the 
lowest value of the contents of the data items identified by the KEY data-names to 
the highest value, according to the rules for comparison of operands in a relation 
condition. 


e When the DESCENDING phrase is specified, the merged sequence is from the 
highest value of the contents of the data items identified by the KEY data-names to 
the lowest value, according to the rules for comparison of operands in a relation 
condition. 


data-names 


Data-name-1, data-name-2, data-name-3, and data-name-4 are KEY data-names and are 
subject to the following rules: 


- The data items identified by KEY data names must be described in records 


associated with file-name-1. 
e KEY data-names can be qualified. 
e The data items identified by KEY data-names must not be variable-length items. 


e If file-name-1 has more than one record description, all the data items identified 
by KEY data-names can be described in one of the record descriptions or in any 
combination of record descriptions. The KEY data-names in each record description 
need not be described again. 


e None of the data items identified by KEY data-names can be described by an entry 
that either contains an OCCURS clause or is subordinate to an entry wet contains 
an OCCURS clause. 


COLLATING SEQUENCE 


The collating sequence that applies to the comparison of the specified nonnumeric KEY 
data items is determined in the following order of precedence: 


1. The collating sequence established by the eens SEQUENCE phrase, if . 
specified, in that MERGE statement 


2. The collating sequence established as the program-collating sequence 


USING (Unisys. Extension) 
As many as eight file-names can be specified in the USING clause. 


The LOCK, PURGE, and RELEASE options can be used to specify the type of file close 
operation for the USING files, file-name-2, file-name-3, file-name-4, and so forth. 
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OUTPUT PROCEDURE 


The OUTPUT PROCEDURE clause must consist of one or more paragraphs or 

sections that appear contiguously in a source program and do not form a part of any 
other procedure. To make merged records available for processing, the OUTPUT 
PROCEDURE clause must include execution of at least one RETURN statement. 
Control must not be passed to the OUTPUT PROCEDURE clause except when a related 
SORT or MERGE statement is being executed. The OUTPUT PROCEDURE clause can 
consist of any procedures needed to select, modify, or copy the records being returned 
one at a time in merged order from file-name-1. The restrictions on the procedural 
statements in the OUTPUT PROCEDURE clause are as follows: 


e The OUTPUT PROCEDURE clause must not contain any transfers of control to 
points outside the output procedure. ALTER, GO TO, and PERFORM statements in 
the OUTPUT PROCEDURE clause cannot refer to procedure-names outside the 
output procedure. COBOL statements are allowed that cause an implied transfer of 
control to declaratives. 


e The OUTPUT PROCEDURE clause must not contain any SORT or MERGE 
statements. 


e The remainder of the PROCEDURE DIVISION must not contain any transfers of 
control to points inside the output procedures. ALTER, GO TO, and PERFORM 
statements in the remainder of the PROCEDURE DIVISION cannot refer to 
procedure-names in the output procedures. 


If an OUTPUT PROCEDURE clause is specified, control passes to it during execution 
of the MERGE statement. The compiler inserts a return mechanism at the end 

of the output procedure. When control passes to the last statement in the output 
procedure, the return mechanism ends the merge operation and passes control to the 
next.executable statement after the MERGE statement. Before entering the output 
procedure, the merge procedure reaches a point at which it can select the next record in 
merged order when requested. The RETURN statements in the output procedure are 
the requests for the next record. 


GIVING 


If the GIVING phrase is specified, all merged records in file-name-1 are automatically 
written on file-name-5. 


section-name-1 and section-name-2 


Section-name-1 and section-name-2 represents the names of OUTPUT PROCEDURE 
clauses.. 


THRU and THROUGH 


The words THRU and THROUGH are esuivalent They indicate a range of OUTPUT 
PROCEDURE clauses. 
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SAVE, LOCK, RELEASE, NO REWIND. and CRUNCH 


The SAVE, LOCK, RELEASE, NO REWIND, and CRUNCH options can be used to 
specify the type of file close operation for the GIVING file-name-5 phrase. 


See Also 


For information on closing files, refer to “CLOSE” earlier in this section. 


MOVE 


The MOVE statement transfers data to one or more receiving data items. 


When a sending item and a receiving item in the same MOVE statement share a part, 
but not all, of their storage areas, the result of the statement execution is undefined. 


The MOVE statement has the following three formats: 


Format Explanation . 
1 This format transfers data to one or more data areas. 
2 The MOVE CORRESPONDING format transfers selected items in identifier-1 to 


selected items in identifier-2. This format transfers items having the same name 
as an item in the receiving field to that corresponding field. 


3 This format transfers selected bit ranges between two BINARY data items. 


Format 1 


MOVE erie 
literal-1 


} TO identifier-2 [ , identifier-3 ]... 


Explanation of Format 1 
Identifier-1 and literal-1 represent the sending area. 


The data designated by literal-1 or identifier-1 are moved first to identifier-2, then 

to identifier-3, and so on. The rules referring to identifier-2 also apply to the other 
receiving areas. Any subscripting or indexing associated with identifier-2, identifier-3, 
and so forth is evaluated immediately before the data is moved to the respective data 
item. 


An index data item cannot appear as an operand of a MOVE statement. 
Any MOVE statement in which the sending and receiving items are both elementary 


items is considered an elementary move operation. Every elementary item belongs to 
one of the following categories: numeric, alphabetic, alphanumeric, numeric-edited, 
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alphanumeric-edited, Kanji, or Kanji-edited. These categories are determined by the 
PICTURE clause. Numeric literals belong to the category numeric; nonnumeric literals 
belong to the category alphanumeric. The figurative constant ZERO belongs to the 
category numeric. The figurative constant SPACE belongs to the category alphabetic. 
All other figurative constants belong to the category alphanumeric. 


The following rules apply to an elementary move between these categories: 


The figurative constant SPACE ora numeric-edited, an alphanumeric-edited, or an 
alphabetic data item must not be moved to a numeric or a numeric-edited data item. 


A numeric literal, the figurative constant ZERO, a numeric data item, or a 
numeric-edited data item must not be moved to an alphabetic data item. 


A noninteger numeric literal or a noninteger numeric data item must not be moved 
to an alphanumeric or an alphanumeric-edited data item. 


An undigit literal must not be moved to a usage DISPLAY, numeric, numeric-edited, 
or alphanumeric-edited data item. Otherwise, subsequent operations on these items 
can be unpredictable. (Undigit literals are a Unisys extension.) 


When moving the figurative constant ZERO to a BINARY item, the result is 


_anumeric zero (all bits off). When moving the figurative constant ZERO toa 


COMPUTATIONAL or DISPLAY item, the result is EBCDIC zeros. 


A Kanji data item or a Kanji-edited data item can be moved only to a Kanji data item 
or a Kanji-edited data item, respectively. All other items cannot be moved to a Kanji 
data item or a Kanji-edited data item. 


All other elementary moves are legal and are performed according to the rules given in 
the following paragraphs. 


Any necessary conversion of data from one form of internal representation to another 
takes place during legal elementary moves along with any editing specified for the 
receiving data item, as follows: 


When an alphanumeric-edited or an alphanumeric item is a receiving item, alignment 
by decimal point and any necessary zero-filling takes place according to the data 
alignment rules. If the size of the sending item is greater than the size of the 
receiving item, the excess characters are right-truncated after the receiving item is 
filled. 


If the sending item is described as signed numeric, the operational sign is not moved. 
If the operational sign occupies a separate character position, that character is not 
moved, and the size of the sending item is considered to be one less than its actual 
size (in terms of standard data format characters). 
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When a numeric or a numeric-edited item is the receiving item, alignment by decimal 
point and any necessary zero-filling take place according to data alignment rules, 
except where zeros are replaced because of editing requirements. 


— When a signed numeric item is the receiving item, the sign of the sending item is 
placed in the receiving item. Conversion of the representation of the sign takes 
place as necessary. If the sending item i is unsigned, a positive sign is generated 
for the receiving item. 


- When an unsigned numeric item is the receiving item, the absolute value of the 
sending item is moved and no operational sign is generated for the receiving 
item. 


— When an alphanumeric data item is the sending item, data is moved as if the 
sending item were described as an unsigned numeric integer. 


— Ifany digits of a sending COMPUTATIONAL numeric item are greater than 9, 
they can be changed when moved from the source. If you wish to preserve these 
values, you must use nonnumeric moves. 


When a receiving field is described as alphabetic, justification and any necessary 
space-filling take place according to data-alignment rules. If the size of the sending 
item is greater than the size of the receiving item, the excess characters are 
right-truncated after the receiving item is filled. 


If the receiving item has an associated TYPE clause, the clause contains the data 
formatted using the type, convention, and language declared for the item. If the 
item does not have an associated convention or language declared, the system 
determines the convention or language based on a default hierarchy. 


The sending item must be a nonnumeric literal or an identifier with the USAGE IS 
DISPLAY clause. 


Any move operation that is not an elementary move is treated like an 
alphanumeric-to-alphanumeric elementary move. In such a move, the receiving area 
is filled without regard to the individual elementary or group items contained in 
either the sending or the receiving area. This rule applies regardless of the declared 
or implied usage of either the source or the destination field. A move operation 

in which either the source field or the destination field is a group item is thus 
unconditionally treated as a transfer of EBCDIC characters with EBCDIC space-fill if 
the source is shorter than the destination. 


It is important to note that when the source field is a group item and the destination 
field is an elementary COMPUTATIONAL item, or vice versa, and the source field 
is shorter than the destination field, the system performs space-fill by inserting 
single-digit zeros as needed, such that the EBCDIC spaces are always aligned on 
byte boundaries. 


In nonelementary moves, USAGE REAL elementary items are treated like 
6-character DISPLAY items, USAGE DOUBLE elementary items are treated like 
12-character DISPLAY items, USAGE BINARY items not longer than 11 digits are 
treated like 6-character DISPLAY items, and USAGE BINARY items longer than 11 
digits are treated like 12-character DISPLAY items.. 
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Table 9-9 summarizes the legality of the various types of MOVE statements. For 
example, a numeric noninteger can be moved to a numeric integer, a numeric noninteger, 
or a numeric-edited field. 


Table 9-9. Comparison of Sending and Receiving Items in MOVE Statements 


5 Category of Receiving Data Item 


Numeric Integer, 
Category of Alphanumeric Numeric Kanji and 


Sending Edited and Noninteger, and Kanji- 
Data Item Alphabetic Alphanumeric Numeric-Edited Edited 


Alphabetic 


Alphanumeric 


Alphanumeric- 
edited 


Numeric 
integer 


Numeric 
noninteger 


Numeric- 
edited 


Kanji 


Kanji- 
edited 


See Also 


e Fora description of the way data is aligned in a receiving item, refer to “Aligning 
Data” in Section 6, “Data Concepts.” 


e For information about the position and representation of the operational sign, refer 
to “SIGN Clause” in Section 7, “DATA DIVISION.” 


Format 2 


MOVE. CORRESPONDING 


CORR 


} identifier-1 TO identifier-2 


8600 0296-000 | — 971 


PROCEDURE DIVISION Statements 


Explanation of Format 2 

CORR is an abbreviation for CORRESPONDING. 

When the CORRESPONDING phrase is used, both identifiers must be group items. 

If the CORRESPONDING phrase is used, selected items in identifier-1 are moved to 

selected items in identifier-2, according to the rules for the CORRESPONDING phrase 
- in Section 8. The'results are the same as if each eu of corresponding identifiers were 


referenced in separate MOVE statements. 


An index data item cannot appear as an soeeand of a MOVE statement. 


See Also 


Refer to “CORRESPONDING Phrase” in Section 8, “PROCEDURE DIVISION 
Concepts,” for information about corresponding move operations. 


Format 3 (Unisys Extension) 


MOVE identifier-4 TO identifier-5 


literal-2 
~ [arithmetic-expression-1 


_ fliteral-3 _ filiteral-4 
* | arithmetic-expression-2 J * | arithmetic-expression-3 J - 


Explanation of Format 3 
Identifier-4 represents the sending area and identifier-5 represents the receiving area. 
An index data item cannot appear as an operand of a MOVE statement. 


Format 3 of the MOVE statement allows bit manipulation and character manipulation. » 
The left and right brackets and the colons are required. The declarations of identifier-4 
and identifier-5 must be such that they are single-precision word-oriented items (either 
USAGE BINARY with fewer than 12 digits in the PICTURE clause, or USAGE REAL). 


A Format 3 MOVE statement moves bits from identifier-4 into identifier-5 with only 
the indicated bits of identifier-5 being changed. Literal-2 or arithmetic-expression-1 
represents the location in identifier-4 at which the transfer begins (that is, the source 
bit position). Literal-3 or arithmetic-expression-2 represents the location in identifier-5 
at which the transfer begins (that is, the destination bit position). Literal-4 or 
arithmetic-expression-3 represents the number of bits to be transferred. 
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The bits in a word-oriented numeric item are numbered 47 through 0, from left to right. 
Therefore, only 0 through 47 are valid numbers for source and destination bit positions. 


Note that the compiler ensures that unsigned USAGE BINARY items never have 
negative values when they are stored in memory. The compiler unconditionally resets 
the sign bit of an unsigned binary item before storing it. As a result, bit 46 of such an 
item is always reset in memory even if it is explicitly set by a Format 3 MOVE statement. 
It is therefore better to ensure that the program declares items referred to in Format 3 
MOVE statements either as signed USAGE BINARY items (an S appears in the 
PICTURE clause) or as USAGE REAL items. 


Examples of Format 3 

The following statements unpack a BINARY word that contains two 20-bit fields: 
MOVE A-AND-B-BOTH TO A-ONLY [39:19:20]. | 
MOVE A-AND-B-BOTH TO B-ONLY [19:19:20]. 

The following two statements repack the fields: 
MOVE B-ONLY TO A-AND-B-BOTH. 


MOVE A-ONLY TO A-AND-B-BOTH [19:39:20]. 


MULTIPLY 


The MULTIPLY statement multiplies numeric data items and sets the values of data 
items equal to the results. | } 
The MULTIPLY statement has the following two formats: 

Format Explanation 


ol Multiplies the value of identifier-1 by the value of identifier-2, identifier-3, and so 
on. The product is stored in identifier-2, identifier-3, and so on. 


2 Multiplies the value of identifier-1 or literal-1 by the value of identifier-2 or 
literal-2. The product is stored in identifier-3, identifier-4, and so on. 
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BY identifier-2 | ROUNDED ] 


MULTIPLY 


identifier-1 } 
literal-1 


[, identifier-8 [ ROUNDED ] ]... 


[ ; ON SIZE ERROR imperative-statement | 


Explanation of Format 1 


When Format 1 is used, the value of identifier-1 or literal-1 is multiplied by the value of 
identifier-2. The value of the multiplier (identifier-2) is replaced by this product; this 
process is then repeated for identifier-1 or literal-1 and for identifier-3, and so forth. 


Each literal must be a numeric literal. 
Kach identifier must refer to a numeric elementary item. 
The imperative-statement can be the NEXT SENTENCE phrase. 


_ The composite of operands (which is the hypothetical data item resulting from the 
superimposition of all receiving data items of a given statement aligned by their decimal 
points) must not contain more than 18 digits. 


Format 2 


B 


MULTIPLY earl } 


at 
literal-1 


literal-2 


GIVING identifier-3 [ ROUNDED | [,, identifier-4 [ROUNDED ] ] ... 


[ ; ON SIZE ERROR imperative-statement | 


Explanation of Format 2 


When Format 2 is used, the value of identifier-1 or literal-1 is multiplied by the value of 
identifier-2 or literal-2; the result is stored in identifier-3, identifier-4, and so forth. 
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Each literal must be a numeric literal. 


Each identifier following the word GIVING must refer either to an elementary numeric 
item or to an elementary numeric-edited item. 


The composite of operands (which is the hypothetical data item resulting from the 
superimposition of all receiving data items of a given statement aligned by their decimal 
points) must not contain more than 18 digits. 


The imperative-statement can be the NEXT SENTENCE phrase. 


General Rules 
The following information applies to all the formats. 


When a sending item and a receiving item in the same MULTIPLY statement share 
a part, but not all, of their storage areas, the result of the statement execution is 
undefined. 


Note that unpredictable results occur in a Format 1 MULTIPLY statement if the same 
operand appears more than once in the list of multiplicands that follows the word BY in 
the statement. For example, assuming X contains the value 9 and Y contains the value 2, 
the value of X is 18 rather than 72 after execution of the following statement: 


MULTIPLY Y BY X, X, X 


OPEN 


The OPEN statement makes a file available for processing. It does not affect the 
contents or availability of the record area of the file. The OPEN statement also specifies 
what kinds of I/O operations are allowed for that file. You might designate, for example, 
an input file to be read by the program and an output file to which records are written by 
the program. 


The OPEN statement has the following two formats: 


Format Explanation 
] Opens a file for sequential, relative, and indexed I/O applications 
2 Opens a port file 


Format 1: Sequential, Relative, and Indexed 1/O 


Format 1 is used for files with sequential, relative, and indexed organization. A 
sequential I/O operation is performed when a program acts on a sequential file, a relative 
I/O operation is performed when a program acts on a relative file, and an indexed I/O 
operation is performed when a program acts on an indexed file. For example, a program — 
randomly accessing a sequential file performs a sequential I/O operation, and a program 
sequentially accessing a relative file performs a relative I/O operation. 
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The general format of this statement is as follows: 


INPUT file-name-1 | WITH NO REWIND 
WITH LOCK 


REVERSED | | 


REVERSED | 


, fileename-2 | WITH NO REWIND 
WITH LOCK 


OUTPUT file-name-3 [ WITH NO REWIND | 
[ , file-name-4 | WITH NO REWIND ] | ... 


1-O file-name-5 | WITH LOCK ] |, file-name-6 [| WITH LOCK | ] ... 


EXTEND file-name-7 | WITH LOCK | 
[ , file-name-8 | WITH LOCK ] ]... 


AVAILABLE EXTEND file-name-9 [ WITH LOCK ] 
[ , file-name-10 [ WITH LOCK ] ] ... 


Note: The AVAILABLE EXTEND, EXTEND, NO REWIND, and 
REVERSED phrases apply only to sequential files. 


Explanation of Format 1 


The INPUT phrase opens the file for reading only. The OPEN INPUT statement makes 
the file available for reading by positioning the current-record pointer at the first record 
in the file. The first read operation of an open file causes an At End condition if the file 
has no records or if it is an optional file that is not present. 


The OUTPUT phrase opens the file for writing only. A successful OPEN OUTPUT 
statement creates a new file, provided you have not previously closed and retained a file 


with the same name. 


The I-O phrase opens the file for both reading and writing. Because this phrase implies 


_ the existence of the file, you cannot use it to create a file. The OPEN I-O statement 


positions the current-record pointer at the first record present in the file. The first read 
operation of the file causes an At End condition if the file has no records. 


The EXTEND phrase opens a sequential file so that new records can be written to 
the end. The OPEN EXTEND statement positions the current-record pointer at the 
end of the file. Subsequent records that are written are added as if the file had been 


- opened with the OPEN OUTPUT statement. You cannot use the EXTEND phrase with 


multiple-reel files. 
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The AVAILABLE EXTEND phrase opens a sequential file so that new records can be 
written to the end of the file. If the file cannot be opened, the program is not suspended 
and operator intervention is not required. The program can determine the cause of the 
open failure by examining the value of the AVAILABLE file attribute. 


File-name-1 through file-name-10 designate files that must be named in the SELECT 
clause and described in the INPUT-OUTPUT SECTION and FILE SECTION of your 
program. You can open files of differing organizations and access types with one OPEN 
statement. The REVERSED option designates that the sequential file is read in reverse 
order, beginning with the last record first. An OPEN INPUT REVERSED statement 
positions the current-record pointer at the end of the file. This statement is meaningful 
for sequential single-reel files, but is ignored if the statement does not apply to the 
storage medium on which the file resides. 


The NO REWIND option opens the sequential file without repositioning the 
current-record pointer. The OPEN INPUT WITH NO REWIND or OPEN OUTPUT 
WITH NO REWIND statements are meaningful for sequential files, but are ignored if 
these statements do not apply to the storage medium on which the file resides. The 
WITH NO REWIND phrase is useful for opening the next file on a multiple-file tape. 


The LOCK phrase opens the file if it is available. The WITH LOCK phrase is meaningful 
for mass-storage files; it is ignored for all other files. 


The LOCK operation works as follows: 


7 If another program has already opened the ale; the system suspends your program 
until the file is exclusively available. 


e Ifno program has opened the file, the file is opened. 


The LOCK phrase is controlled by the EXCLUSIVE file attribute. When you open 

and lock a file using an OPEN WITH LOCK statement, the value of the EXCLUSIVE 
attribute becomes TRUE when the file is opened. If you close the file without retaining 
it, the value of the EXCLUSIVE attribute becomes FALSE when the file is closed. This - 
value ensures that other programs can access that file. 


Unisys recommends that you do not directly use the EXCLUSIVE file attribute because 
you might interfere with the lock mechanism and cause unexpected results in your 
program. 


General Rules 


You can open and close a file many times in a program by using any of the syntax options. 
To reopen a file after you open it initially, you must first close the file without specifying 
the REEL, UNIT, or LOCK phrase. 


Because the sort module has opening routines for files associated with the USING and 
the GIVING phrases of the SORT and MERGE statements, your program must not open 
these files with an OPEN statement. 
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Example 


Many programs open all files at the beginning of the PROCEDURE DIVISION. Although 
you can use a separate OPEN statement for each file, typically you open many files with 
one OPEN statement. 


A sample of this type of OPEN statement is shown in Example 9-19. This example does 
the following operations: . 


e Creates a file called GUEST-FOLIO 


e Opens two existing files, ROOM-STATUS and RESERVATIONS, for update; allows 
no other programs to access these files while they are open 


e Opens the file ROOM-AVAIL for reading in reverse order 


e Opens the file CREDIT-CHARGE so that records can be added at the end of the file, 
and allows no other programs to access the file while it is open 


PROCEDURE DIVISION. 
OPEN-PARA. 
OPEN OUTPUT GUEST-FOLIO, 
I-O0 ROOM-STATUS WITH LOCK, RESERVATIONS WITH LOCK, 
INPUT ROOM-AVAIL REVERSED, 
AVAILABLE EXTEND CREDIT-CHARGE WITH LOCK. 


Example 9-19. Coding an OPEN Statement 


See Also 


e For information about handling an At End condition that occurs during a read 
operation, refer to “READ” later in this section. 


e For information about the meanings of status code values, refer to “I/O Status” in 
Section 5, “ENVIRONMENT DIVISION.” 


e For information about the AVAILABLE and EXCLUSIVE attributes, refer to the 
File Attributes Reference Manual. 


Open Modes 


A successfully opened file is considered to be in an open mode. The open modes include 
INPUT, OUTPUT, I-O, and EXTEND. These modes correspond to the phrases of 

the same name allowed for the OPEN statement. The type of open mode, the file 
organization, and the method of file access determine the I/O statements that are 
permitted in your program. 
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Table 9-10 shows the I/O statements you can perform with each open mode and the 
method of file access for files with sequential organization. 


Table 9-10. 1/O Statements Allowed for Open Files with Sequential Organization 


Open Mode Statements Allowed 
INPUT READ 
OUTPUT WRITE 
i-0 READ, REWRITE 
READ, WRITE, REWRITE 
EXTEND WRITE 
Legend — 
S Sequential 
R Random 


Table 9-11 shows the I/O statements you can use with each open mode and the method 
of file access for files with relative or indexed organization. 


Table 9-11. 1/O Statements Allowed for Open Files with Relative or Indexed | 
Organization 


Open Mode . Statements Allowed 
INPUT READ, START 
READ 


OUTPUT WRITE 
I-O READ, REWRITE, START, DELETE 
READ, WRITE, REWRITE, DELETE 
~ READ, WRITE, REWRITE, START, DELETE 


Legend 

S Sequential 
R Random 
D Dynamic 


Format 2: Opening Port Files (Unisys Extension) 


Before a dialogue can be established between two programs that communicate 

through a port file, each program must open a subfile. The system establishes the 
logical communication path between the two port files, provided that the connection 
descriptions of the two files match. Because the two programs run independently, one 
program cannot affect when the subfile of the other program is open. The OPEN 
statement for port files enables a program to request that a dialogue be established with 
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a correspondent endpoint without the programming determining whether the subfile of 
the correspondent endpoint is open. 


The general format of this statement is as follows: 


1-0 {file-name-1} ... 
OFFER 
AVAILABLE 
WITH NO WAIT 
WITH WAIT 

CONNECT-TIME-LIMIT 
) 


{file-name-2}... 


integer-1 
ASSOCIATED-DATA-LENGTH 
USING r ere \ 
integer-2 
ASSOCIATED-DATA 
{ identifier-3 \ 
literal 


Explanation of Format 2 


The I-O phrase opens the file for both input and output operations. No further options 
can be specified. The WAIT option is the default control option. 


File-name-1 can designate the port file to open. 
File-name-2 must designate the port file to open 


The OFFER phrase opens the port file and returns control to the program after you 
determine the availability of the host by using the YOURHOST file attribute. If the 
program specifies subfiles, the OPEN OFFER statement returns control to the program 
after the availability of the correspondent endpoint is determined for all subfiles. The 
dialogue is then established in parallel with the processing of the program. 


The AVAILABLE phrase opens a subfile that matches a subfile that has already been 
offered. If no subfile has been offered, the subfile remains closed and is not considered 
for subsequent matching. This phrase is the same as an OPEN WAIT statement with 
the AVAILABLEONLY file attribute set to TRUE. 


The NO WAIT phrase opens the port file and returns control to the program as soon as 
the OPEN NO WAIT statement is checked for correctness. The dialogue is established 
while the program continues processing. 


8600 0296-000 


PROCEDURE DIVISION Statements 


Note: Your program might be significantly delayed while the availability 
of the correspondent endpoint is determined. If this delay is 
undesirable, use the OPEN NO WAIT statement. 


The WAIT phrase opens the port file and suspends the program until either the dialogue 
is established or the open operation fails. If the program specifies subfiles, the OPEN 
WAIT statement suspends the program until the open operation on each subfile succeeds 
or fails. The OPEN WAIT statement is the default statement and is used if no OPEN 
statement option is specified in your program. 


The CONNECT-TIME-LIMIT option indicates the time in minutes that the system 
allows for establishing a dialogue. The open operation fails if a correspondent endpoint is 
not found in that amount of time. If you do not use the CONNECT-TIME-LIMIT phrase 
or if you specify a value of 0 (zero), the system allows an indefinite amount of time to 
establish a dialogue. An error results or if you specify a negative or noninteger value. 


The ASSOCIATED-DATA-LENGTH option specifies the number of characters of 
associated data to be sent. If you do not specify the length of the associated data and 
the associated data is a data item, your program uses the actual length of the data. If 
you do specify the length of the associated data, the length value must be less than or 

~ equal to the actual length of the data. An error results if the length specified is not a 
single-precision integer value. 


The ASSOCIATED-DATA option transfers data to the correspondent endpoint along 
with the open request for some types of networks. 


Identifier-1 through identifier-3 designate elementary integer data items. Identifier- 3 
can also designate a group data item. 


Integer-1 and integer-2 must be integer numeric literals. 


This literal specifies either a nonnumeric or hex literal. 


General Rules 


In addition to deciding the method of opening a subfile, you need to designate the 
subfiles to open. If you want to designate more than one subfile, make sure your 
program includes code to perform the following tasks: 


1. Specify the total number of subfiles in your program by using the CHANGE 
ATTRIBUTE MAXSUBFILES TO VALUE attribute-value statement. 


2. Specify the subfiles to open by using the SELECT port-file ce GN TO PORT; 
ACTUAL KEY IS subfile-num clause. 


3. Declare subfile-num and attribute-value i in the WORKING-STORAGE SECTION. 
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Table 9-12 shows how the value specified in the ACTUAL KEY clause determines which 
subfile is opened. . 


Table 9-12. Designating Subfiles to Open 


Actual Key Value 7 Explanation 


0 . Opens every closed subfile 
Nonzero | Opens the specified subfile 
None Opens a single subfile 


Greater than the MAXSUBFILES Returns a BADSUBFILEINDEX run-time error in the 
value or a negative number SUBFILERROR attribute 


Examples . . 


In Examples 9-20 through 9-22, it is assumed that earlier in the program the port files 
were declared using an ACTUAL KEY clause to specify a subfile index and that the 
subfile index was set to a particular subfile. 

Example 9-20 opens port file PORTFILE]1 and offers it for matching. The program is 
suspended until a matching subfile is found or until 10 minutes have elapsed. _ 


OPEN WAIT PORTFILE1 
USING CONNECT-TIME-LIMIT OF 19. 


Example 9-20. Coding an OPEN WAIT Statement 


Example 9-21 opens port file PORTFILE1 with the control option set to OFFER. 
Control is returned to the program as soon as it is determined that the host can be 
reached. When a matching subfile is found, the information "MYDATA" is sent to the 
other process as associated data during the OPEN process. 


OPEN OFFER PORTFILE1 
ASSOCIATED-DATA OF “MYDATA". 


Example 9-21. Coding an OPEN OFFER Statement 


Example 9-22 offers port files PORTFILE1 and PORTFILE2 for matching. The NO 
WAIT option indicates that control is returned to the program as soon as the open 
process begins. Fourteen characters of information are sent to the other process 

as associated data with the connect request, beginning at the location pointed to by 
GROUP-ITEM. 


OPEN NO WAIT PORTFILE1 PORTFILE2 
USING ASSOCIATED-DATA OF GROUP-ITEM 
ASSOCIATED-DATA-LENGTH OF 14. 


Example 9-22. Coding an OPEN NO WAIT Statement 


8600 0296-000 


PROCEDURE DIVISION Statements 


See Also 


e For information about another type of open operation used to establish a dialogue, 
refer to “AWAIT-OPEN (Unisys Extension)” earlier in this section. 


e For step-by-step information on coding port file applications, refer to the I/O 
Subsystem Programming Guide. 


e For references to file attributes, refer to the File Attributes Reference Manual. 


I/O Status Value 


The system returns a value that indicates the result of an OPEN statement. You can 
access this value by including a SELECT file-name FILE STATUS IS data-name clause 
in your program. The operating system moves a value into the designated data-name 
storage area after the program performs the OPEN statement. You can then use an IF 
statement to test the value of the data-name and take the desired action depending on 
the result. Ifyou choose not to code an action for the result of an open operation, the 
system provides a default action for each result. 


If your program does not include either a FILE STATUS clause or an ERROR 
PROCEDURE clause in the DECLARATIVES SECTION for the file, the system aborts 


the program if the open operation is unsuccessful. - 


Table 9-18 shows the I/O status values and their meanings. 


Table 9-13. I/O Status Values for OPEN Statement 


Explanation 


Control was returned to the program after the OPEN statement completed 
correctly. In the case of a port file, the open operation might be pending. 


An error was detected while the file was being opened. ~ 


t Unisys extension 


PERFORM 


The PERFORM statement transfers control explicitly to one or more procedures and 
returns control implicitly whenever execution of the specified procedure is complete. 


The PERFORM statement has the following four formats: 
Format Explanation | 


1 Executes the specified procedures and then transfers control to the next 
instruction after the PERFORM statement. 


2 Executes procedures a specified number of times. 


continued 
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PERFORM procedure-name-1 | { 
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continued 
Format ——SM Explanation 

3 Executes procedures until a specified condition is TRUE. 

4 Executes procedures repetitively, increasing or decreasing the value of a counter 
data item once for each repetition until one or more conditions are satisfied. The 
conditions that end the repetitions are tested before the procedures are executed. 

Format 1 


THROUGH 


THRU } procedure-name-2 


Explanation of Format 1 


Format 1 is the basic PERFORM statement. A procedure referenced by this type of 
PERFORM statement is executed once, and control then passes to the next executable 
statement following the PERFORM statement. 


procedure-name-1 THROUGH procedure-name-2 


When the PERFORM statement is executed, the program transfers control from 

the PERFORM statement to the first statement of the procedure named by 
procedure-name-1. This transfer occurs.only once for each execution of a PERFORM 
statement. The program transfers control from the procedure to the next executable 
statement following the PERFORM statement, as follows: 


e If procedure-name-1 is a paragraph-name and procedure-name-2 is not specified, the 
program returns control after the last statement of procedure-name-1. 


e Ifprocedure-name-1 is a section-name and procedure-name-2 is not specified, 
the program returns control after the last statement of the last paragraph in 
procedure-name-1. 


e If procedure-name-2 is specified and is a paragraph-name, the program returns 
control after the last statement of the paragraph. 


e If procedure-name-2 is specified and is a section-name, then the program returns 
control after the last statement of the last paragraph in the section. 


When procedure-name-1 and procedure-name-2 are both specified and one is the name 
of a procedure in the DECLARATIVES SECTION of the program, then both must be 
procedure-names in the same DECLARATIVES SECTION. 


No particular sequential relationship needs to exist between procedure-name-1 


and procedure-name-2. More than one logical path of program control through the 
performed range of procedures can exist. A common, though not required, method of | 
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documenting the final paragraph of a performed range of procedures is through the use 
of the EXIT statement. 


An implicit return mechanism is established at the end of a performed range of 
procedures and is activated by the execution of a PERFORM statement. When program 
control reaches an active return mechanism, control returns to the activating PERFORM 
statement. A return mechanism permanently deactivates itself by transferring program 
control back to a PERFORM statement; an active return mechanism is temporarily 
deactivated by the execution of a PERFORM statement. Program control passes 
through a nonactive return mechanism to the next executable statement following the 
PERFORM range. This rule applies to all formats. . 


A procedure executed under the control of a PERFORM statement can execute 
PERFORM statements. The range of procedures executed under the control of the 
nested PERFORM statement need not be declared totally within, or disjoint from, the 

_range of procedures executed by the first PERFORM statement. The permanent 
deactivation of an active return mechanism causes the last return mechanism 
temporarily deactivated to become active again, allowing overlapping PERFORM ranges 
(two or more PERFORM ranges that have a common exit point) to logically execute in 
the same way as disjoint PERFORM ranges. 


Transfer of program control by means of a GO statement from a range of procedures 
being executed under control of a PERFORM statement does not cause the return 
mechanism to be deactivated. Subsequent transfer of program control back into the 
PERFORM range causes control to return to the PERFORM statement, provided that 
the return mechanism is still active. Repeated branching out of a PERFORM range 
without allowing control to reach the ending paragraph can cause the program to end 
with a STACK OVERFLOW fault. 


Note: A RELEASE statement in a SORT INPUT procedure and 
a RETURN statement in a SORT OUTPUT procedure will 
conditionally cause the program to terminate with an INVALID 
INDEX error if either statement is executed when the PERFORM 
statement nesting level is greater than 32. This is a permanent 
nesting-level restriction. 


When procedure-name-1 and procedure-name-2 are both specified and one is the name 
of a procedure in the DECLARATIVES SECTION of the program, then both must be 
-procedure-names in the same DECLARATIVES SECTION. 


-The words THRU and THROUGH are equivalent. 
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Format 2 


THROUGH 


PERFORM procedure-name-1 | ett 


} procedure-name-2 


identifier-1 
integer-1 


} TIMES 


Explanation of Format 2 


Format 2 is the PERFORM...TIMES variation. The procedures are performed the 
number of times specified by integer-1 or by the initial value of the data item referenced 
by identifier-1 for that execution. If, at the time of execution of a PERFORM statement, 
the value of the data item referenced by identifier-1 is equal to 0 or is negative, then 
control passes to the next executable statement following the PERFORM statement. 
After the procedures have been executed the specified number of times, control is 
transferred to the next executable statement following the PERFORM statement. 


procedure-name-l1 THROUGH procedure-name-2 


Refer to the discussion of procedure-name-1 THROUGH procedure-name-2 in Format 1 
of the PERFORM statement for information. 


TIMES 


. Each identifier represents an elementary numeric item described in the DATA 
DIVISION. Identifier-1 must be described as a numeric integer. 


During execution of the PERFORM statement, references to identifier-1 cannot alter 


the number of times the procedures are to be executed as specified by the initial value of 
identifier-1. 


Format 3 


THROUGH 
THRU 


PERFORM procedure-name-1 { 


} procedure-name-2 


UNTIL condition-1 
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Explanation of Format 3 


Format 3 is the PERFORM...UNTIL variation. The specified procedures are performed 
until the condition specified by the UNTIL phrase is TRUE. When the condition is 
TRUE, control is transferred to the next executable statement after the PERFORM 
statement. If the condition is TRUE when the PERFORM statement is entered, no 
control transfer to procedure-name-1 takes place, and control is passed to the next 
executable statement following the PERFORM statement. 


procedure-name-1 THROUGH procedure-name-2 


Refer to the discussion of procedure-name-1 THROUGH procedure-name-2 in Format 1 
of the PERFORM statement for information. 


| UNTIL 


Condition-1 can be any conditional expression described according to the rules for 
conditional expressions. 


Format 4 


THROUGH 


PERFORM procedure-name-1 heer 


} provedure-name-2 


identifier-3 


~ VARYING eae } FROM nda 
index-name-1 ; 
literal-1 


BY a UNTIL condition-1 
literal-2 - 


identifier-6 


index-name-3 


AFTER nae } FROM nde 


literal-3 


BY fo UNTIL condition-2 
literal-4 —— 
identifier-9 


AFTER { gee? FROM sndex-named 
7 index-name-5 
literal-5 


BY { toy } UNTIL condition-3 


literal-6 
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Explanation of Format 4 

Format 4 is the PERFORM...VARYING variation. The values referenced by one or more 
identifiers or index-names are incremented or decremented in an orderly fashion during 
execution of a PERFORM statement 


In the following discussion, every reference to an identifier as the object of the 
VARYING, AFTER, and FROM (current eae phrases also refers to index-names. 


Condition-1, condition-2, and condition-3 can be any conditional expression described 
according to the rules for conditional expressions. 


Each identifier represents an elementary numeric item described in the DATA 
DIVISION. 


Each literal represents a numeric literal. 


procedure-name-1 THROUGH procedure-name-2 


Refer to the discussion of procedure-name-1 THROUGH procedure-name-2 in Format 1 
of the PERFORM statement for information. 


VARYING 


The VARYING phrase specifies a data item that tracks the iterations of the PERFORM 
statement. 


If an index-name is specified in the VARYING phrase, the following conditions apply: 


e The identifier in the associated FROM and BY phrases must be an integer data item. 
e The literal in the associated FROM phrase must be a positive integer. 

e The literal in the associated BY phrase must be a nonzero integer. 

If an index-name is specified in the VARYING or the AFTER phrase and an identifier is 


specified in the associated FROM phrase, then the data item referenced by the identifier 
must have a positive value. 


FROM 


The FROM phrase specifies the initial value of the tracking data item in the VARYING 
phrase. 


If an index-name is specified in the FROM phrase, the following conditions apply: 


e The identifier in the associated VARYING or AFTER phrase must be an integer data 
item. 


e The identifier in the associated BY phrase must be an integer data item. 


e The literal in the associated BY phrase must be a nonzero integer. 
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If an index-name appears in a VARYING phrase, an AFTER phrase, or in both phrases, 
then the index-name is initialized and subsequently incremented (as described in the 
following paragraphs) according to the rules of the SET statement. 

When an index-name appears in the FROM phrase and an identifier appears in an 
associated VARYING or AFTER phrase, the identifier is initialized according to the 


rules of the SET statement. Subsequent incrementation is explained in the flowchart 
descriptions in the text that follows. 


BY 


The BY phrase specifies the value by which the counter data item is incremented. 


UNTIL 


The UNTIL phrase indicates the condition to be tested that, if TRUE, ends the 
iterations of the PERFORM statement. 


AFTER...UNTIL 
The AFTER phrase specifies the next condition to be evaluated. | 
If an index-name is specified in the AFTER phrase, the following conditions apply: 


e The identifier in the associated FROM and BY phrases must be an integer data item. 
e The literal in the associated FROM phrase must be a positive integer. 


e The literal in the associated BY phrase must be a nonzero integer. 


Flowcharts 


Figure 9-1 shows the flowchart for the VARYING phrase with one condition. 


8600 0296-000 - 7 a 9-89 


PROCEDURE DIVISION Statements 


Entrance 


Set 
identifier-2 
equal to 
current FROM value 


condition-1 Exit 


Execute 
procedure-name-1 
THRU 


procedure-name-2 


Increment 
identi fier-2 
with 
current BY value 


Figure 9~1. Flowchart for the VARYING Phrase of a PERFORM Statement with One 
Condition 


When the PERFORM statement has one condition, the following sequence of events 
occurs: 
The program sets identifier-2 to the value established in the FROM phrase. 
The program evaluates condition-1. 


If condition-1 is TRUE when it is evaluated, the program transfers control to the 
next executable statement after the PERFORM statement. 


4. Ifcondition-1 is FALSH, the program executes procedure-name-1 and 
procedure-name-2. 


5. The program increments the value specified in the VARYING phrase by the value 
-designated in the BY phrase. 


Figure 9-2 shows the flowchart for the VARYING phrase with two conditions. 
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Figure 9-2. Flowchart for the VARYING Phrase of a PERFORM Statement with Two 
Conditions 
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Entrance 


Set 
identi fier-2 
and 
identi fier-5 
to 
current FROM values 


FALSE 


TRUE 
condition-2 


Execute 
procedure-name-1 
THRU 


procedure-name-2 


Increment 
identi fier-5 
with 
current BY value 


Increment 
identi fier-5 
with 
current BY value 


Set 


identifier-5 
to 
current FROM value 


Exit 
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When the PERFORM statement has two conditions, the following sequence of events 
occurs: 


1. The program sets identifier-2 and any occurrences of identifier-5 to the value of the 
literal or the current value of the identifier in the associated FROM phrase. 


The program evaluates condition-1. 


If any condition other than the last one is FALSE when it is evaluated, the program 
evaluates the next condition immediately. 


If the last condition is FALSE when it is evaluated, the program executes 
procedure-name-1 through procedure-name-2 once. Then, the program adds 
the last BY value to the associated identifier-2 or identifier-5, and evaluates the 
condition again. 


If condition-1 is TRUE when it is evaluated, the program transfers control to the 
next executable statement after the PERFORM statement. If condition-1 is TRUE 
the first time it is evaluated, the program does not evaluate the remaining conditions 
and does not execute procedure-name-1 through procedure-name-2. 


If condition-2 is TRUE when it is evaluated, the program increments the identifier of 
the immediately preceding AFTER or VARYING phrase by the associated BY value, 
sets the associated identifier-5 to the value of literal-3 or to the current value of 
identifier-6 in the associated FROM phrase, and evaluates the condition specified in 
that preceding AFTER or VARYING phrase. 


See Also 


For information about identifying conditions, refer to “Conditional Expressions” in 
Section 8, “PROCEDURE DIVISION Concepts.” 


PROCESS (Unisys Extension) 


The PROCESS statement initiates the parallel execution of another task. 


The format of the PROCESS statement is as follows: 


PROCESS task-identifier WITH section-name [ USING actual-parameter-list | 


Explanation of Format 


The PROCESS statement creates a dependent process as a separate task. Unlike the 
separate task started by a RUN statement, the task initiated by a PROCESS statement 
depends on the initiator. If the initiator ends before the termination of the dependent 
process, a critical block exit occurs. 


A dependent process must be bound to a host program if the dependent process contains 


data areas described with the GLOBAL or OWN clauses. A dependent process runs in 
its own stack. . 
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The syntax of the PROCESS statement is the same as the CALL statement format 
that initiates a task. The difference is that the CALL statement initiates serial (or 

- synchronous) processing of another program, while the PROCESS statement initiates 
parallel (or asynchronous) processing. 


The actual-parameter-list must consist of a series of data items, task items, and 
expressions, optionally separated by commas. Arithmetic expressions can be passed 
as variables, and certain kinds of variables can be passed (received) by reference. As 
a general rule, the kind of actual parameter must not conflict with the corresponding 
formal parameter. 


See Also 


For an additional explanation of the syntax, refer to “CALL” earlier in this section. 


READ 


The READ statement reads one record from a file on an input device and stores it in 

a record storage area associated with the filename. You must first open a file in the 
INPUT or I-O mode before you can read from it. If the read operation is successful, the 
data is available in the record storage area. | 


For sequential access, the READ statement makes the next logical record from a file 
available. For random access, the READ statement makes a specified record available 
from a mass-storage file. 


The execution of the READ statement causes the value of any FILE STATUS data item 
associated with the file-name to be updated. 


When the logical records of a file are described with more than one record description, 
these records automatically share the same record storage area. This sharing is 
equivalent to an implicit redefinition of the area. The contents of any data items that are 
beyond the range of the current data record are undefined after the READ statement is 
executed. 


The READ statement has the following five formats: 


Format Explanation 


1 ; Reads the next record of any file in sequential access mode, regardless of 
organization. 

2 Reads a record in random or dynamic access mode when the record is retrieved 
randomly. 

3 Reads relative or indexed files in dynamic access mode. 

4 Reads indexed files in random access mode, or reads files in dynamic access 


mode when records are retrieved randomly. 


5 Reads a formlibrary. Refer to Volume 2 for more information. 
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Format 1: Sequential Access 


The READ statement make the next record available as follows: 


e Ifthe open operation positions the current-record pointer, the record indicated by 
the current-record pointer is made available. 


e Ifaread operation positions the current-record pointer, the current-record pointer is 
updated to point to the next record in the file and that record is made available. 


If the position of the current-record pointer for that file is undefined for a read 
operation, the read operation is unsuccessful. 


If the end of a reel or a unit is recognized during execution of a READ statement and the 
logical end of the file has not been reached, the following operations are executed: 


e For an indexed file being sequentially accessed, records with the same duplicate 
value in an alternate record key (the key of reference) are made available in the 
same order they would be in if they were executed with WRITE or REWRITE 
statements that create such duplicate values. 


e Ifthe ACTUAL KEY or RELATIVE KEY phrase is specified for a sequential or a 
relative organization file with sequential access mode, the execution of a READ 
statement updates the contents of the ACTUAL KEY or RELATIVE KEY data item 
to the ordinal number of the logical record accessed. However, if an At End condition 
is reached, the contents of the ACTUAL KEY phrase are not changed. 


The format for sequential access is as follows: 


READ filename RECORD | WITH NO WAIT | [ INTO identifier | 


[ ; AT END imperative-statement | 
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Explanation of Format 1 


Format 1 is used for all files in sequential access mode, regardless of organization. 


WITH NO WAIT (Unisys Extension) 


‘The WITH NO WAIT phrase can be specified only for port files. 


A READ statement causes the program to wait until a logical record is available. For 
port files, you can prevent the possibility of this suspension by specifying the WITH NO 
WAIT phrase. A status key value of 94 indicates that no logical record was available for 
the read operation. | : 


» 
C 
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If you declare an ACTUAL KEY clause for a port file, you are responsible for updating 
the ACTUAL KEY value with an appropriate subfile index. If the ACTUAL KEY value is 
not 0 (zero), a read operation from the specified subfile is performed. If the ACTUAL 
KRY value is 0 (zero), a nonselective read operation is performed and the ACTUAL KEY 
value is updated to indicate the subfile index of the subfile that was read. 


For a nonselective read operation, the first logical record to arrive at a subfile in the 
port file is returned as the data for the READ statement. The subfile to be read is 
determined by the operating system, and no specific selection algorithm is guaranteed. 
However, no subfile is read continuously at the expense of the other subfiles. 


If you do not declare an ACTUAL KEY clause for the port file, the file must contain a 
single subfile and that subfile is read. 


INTO 


If the INTO phrase is specified, the record being read is moved from the record area to 
the area specified by the identifier. The move takes place according to the rules specified 
for the MOVE statement. The sending area is considered to be a group item equal in 
size to the maximum record size for this file. The implied MOVE statement does not 
occur if the read operation was unsuccessful. Any subscripting or indexing associated 
with the identifier is evaluated after the record is read and immediately before the 
record is moved to the data item. 


When the INTO phrase is used, the record being read is available in both the input 
record area and the data area associated with the identifier. The record storage area 
associated with the identifier and the record BtOEAee area associated with file-name must 
not be the same record storage area. 


AT END 


When the At End condition occurs, the read operation is unsuccessful. The following 
actions occur in the order specified: 


1. The system places a value in the FILE STATUS data item (if specified for this file) . 
to indicate an At End condition. 


2. Ifthe program specifies an AT END phrase in the statement that causes the 
condition, the program transfers control to the associated imperative-statement. 
The program cannot execute any USE procedure specified for this file. 


3. Ifthe program does not specify an AT END phrase and does specify a USE 
procedure, the program executes that procedure. If the program does not specify a 
USE procedure, the program ends. 


A READ statement with an AT END phrase transfers control to the imperative- 
statement in the AT END phrase if the READ statement is executed after an At 

End condition has been recognized but before a successful CLOSE statement and a 
successful OPEN statement have been executed for the file. (The ability to read a 
record after the At End condition has been reached and the repeated execution of the 
imperative-statement in the AT END phrase of such READ statements are Unisys 
extensions). . 
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If an optional file is not present when the file is opened, the read operation is 
unsuccessful. The At End condition occurs at execution of the first READ statement for 
the file. The standard end-of-file procedures are not performed. 


The imperative-statement can be the NEXT SENTENCE phrase. 


Format 2: Random Access of Relative or Indexed Files 


For random access of relative files, the execution of a Format 2 READ statement 
accesses the record specified by the contents of the ACTUAL KEY data item or 
RELATIVE KEY data item. If, on execution of a Format 2 READ statement, the 
contents of the ACTUAL KEY data item or RELATIVE KEY data item are less than 
one or greater than the ordinal number of the last record written to the file, the READ 
statement is unsuccessful and the Invalid Key condition results. 


For random access of indexed files, the prime record key is established as the key of © 
reference. The prime record key for the file is the data item specified in the RECORD 


- KEY clause of the file-control-entry for a file. 


The format for random access of relative files or indexed files is as follows: 


READ file-name RECORD | WITH NO WAIT | [ INTO identifier | 


[ ; INVALID KEY imperative-statement | 
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Explanation of Format 2 


Format 2 is used for files in random access or dynamic access mode when records are to 
be retrieved randomly. 


WITH NO WAIT (Unisys Extension) 
The WITH NO WAIT phrase can be specified only for port files. 


A READ statement causes the program to wait until a logical record is available. For 
port files, you can prevent the possibility of this suspension by specifying the WITH NO 
WAIT phrase. A status key value of 94 indicates that no logical record was available for 
the read operation. 


If you declare an ACTUAL KEY clause for a port file, you are responsible for updating 
the ACTUAL KEY value with an appropriate subfile index. If the ACTUAL KEY value is 
not 0 (zero), a read operation from the specified subfile is performed. If the ACTUAL 
KEY value is 0 (zero), a nonselective read operation is performed and the ACTUAL KEY 
value is updated to indicate the subfile index of the subfile that was read. 
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For a nonselective read operation, the first logical record to arrive at a subfile in the 
port file is returned as the data for the READ statement. The subfile to be read is 
determined by the operating system, and no specific selection algorithm is guaranteed. 
However, no subfile is read continuously at the expense of the other subfiles. 


If you do not declare an ACTUAL KEY clause for the port file, the file must contain a 
single subfile and that subfile is read. 


INTO 


If the INTO phrase is specified, the record being read is moved from the record area to 
the area specified by the identifier. The move takes place according to the rules specified 
for the MOVE statement. The sending area is considered to be a group item equal in 
size to the maximum record size for this file. The implied MOVE statement does not 
occur if the read operation was unsuccessful. Any subscripting or indexing associated 
with the identifier is evaluated after the record is read and immediately before the 
record is moved to the data item. 


When the INTO phrase is used, the record being read is available in both the input 
record area and the data area associated with the identifier. The record storage area 
associated with the identifier and the record storage area associated with file-name must 
not be the same storage area. 


INVALID KEY 


When the Invalid Key condition occurs, the read operation is unsuccessful. The following 
actions occur in the order specified: 


1. The system places a value in the FILE STATUS data item (if specified for this file) 
to indicate an Invalid Key condition. 


2. Ifthe program specifies an INVALID KEY phrase in the statement that causes the 
condition, the program transfers control to the associated imperative-statement. 
The program does not execute any USE procedure specified for this file. 


3. Ifthe program does not specify an INVALID KEY phrase and does specify a USE 
procedure, the program executes the USE procedure. If the program does not 
specify a USE procedure, the program ends. 


The imperative-statement can be the NEXT SENTENCE phrase. | 
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Format 3: Dynamic Access of Relative or Indexed I/O Files — 
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The format for dynamic access of relative or indexed files is as follows: 


READ file-name [ NEXT ] RECORD [ INTO identifier | 


[ ; AT END imperative-statement | 


Explanation of Format 3 


Format 3 is used for relative or indexed I/O files in dynamic access mode. 


NEXT 


For indexed files, a READ NEXT statement causes the next logical record to be retrieved 
from that file using the key of reference. 


For relative files, a READ NEXT statement updates the contents of the RELATIVE KEY 
data item so that it contains the ordinal record number of the record made available. 


INTO 


If the INTO phrase is specified, the record being read is moved from the record area to 
the area specified by the identifier. The move takes place according to the rules specified 
for the MOVE statement. The sending area is considered to be a group item equal in 
size to the maximum record size for this file. The implied MOVE statement does not 
occur if the read operation was unsuccessful. Any subscripting or indexing associated 
with the identifier is evaluated after the record is read and immediately before the 
record is moved to the data item. | 


When the INTO phrase is used, the record being read is available in both the input 
record area and the data area associated with the identifier. The record storage area 


- associated with the identifier and the record storage area associated with file-name must 


not be the same storage area. 
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AT END 


When the At End condition occurs, the read operation is unsuccessful. The following 
actions occur in the order specified: 


1. The system places a value in the FILE STATUS data item (if a for this file) 
to indicate an At End condition. 


2. Ifthe program specifies an AT END phrase in the statement that causes the 
condition, the program transfers control to the associated imperative-statement. 
The program does not execute any USE procedure specified for this file. 


8. Ifthe program does not specify an AT END phrase and does specify a USE 
procedure, the program executes that procedure. If the program does not specify a 
USE procedure, the program ends. 


A READ statement with an AT END phrase transfers control to the imperative- 
statement in the AT END phrase if the READ statement is executed after an At 

End condition has been recognized but before a successful CLOSE statement and a 
successful OPEN statement have been executed for the file. (The ability to read a 
record after the At End condition has been reached and the repeated execution of the 
imperative-statement in the AT END phrase of such READ statements are Unisys 
extensions). 


If an optional file is not present when the file is opened, the read operation is 
unsuccessful. The At End condition occurs at execution of the first READ statement for 
the file. The standard end-of-file procedures are not performed. 


The imperative-statement can be the NEXT SENTENCE phrase. 


Format 4: Random Access of Indexed Files 


The format for random access of indexed files is as follows: 


READ file-name RECORD [INTO identifier | [ ; KEY IS data-name ] 


[ ; INVALID KEY imperative-statement | 


Explanation of Format 4 


Format 4 is used for indexed I/O files in random access mode or for files in dynamic 
access mode when records are to be retrieved randomly. 
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INTO 


If the INTO phrase is specified, the record being read is moved from the record area to 
the area specified by the identifier. The move takes place according to the rules specified 
for the MOVE statement. The sending area is considered to be a group item equal in 
size to the maximum record size for this file. The implied MOVE statement does not 
occur if the read operation was unsuccessful. Any subscripting or indexing associated 
with the identifier is evaluated after the record is read and immediately before the 
record is moved to the data item. 


When the INTO phrase is used, the record being read is available in both the input 
record area and the data area associated with the identifier. The record storage area 
associated with the identifier and the record storage area associated with file-name must 
not be the same storage area. 


KEY 


Data-name is established as the key of reference for this retrieval. If the dynamic access 
mode is specified, this key of reference is also used by any subsequent executions of 
Format 4 READ statements for the file until a different key of reference is established 
for the file. 


The data-name must be the name of a data item specified as a record key associated with 
the file-name. The data-name can be qualified. 


Execution of the READ statement causes the value of the key of reference to be 
compared with the value contained in the corresponding data item of the stored records 
in the file until the first record with a matching value is found. The current-record 
pointer indicates this record, which is then made available. If no record can be so 
identified, the Invalid Key condition exists and execution of the READ statement is 
unsuccessful. 


INVALID KEY 


When the Invalid Key condition occurs, the read operation is unsuccessful. The following 
actions occur in the order specified: 


1. The system places a value in the FILE STATUS data item (if specified for this file) 
to indicate an Invalid Key condition. 


2. Ifthe program specifies an INVALID KEY phrase in the statement that causes the 
condition, the program transfers control to the associated imperative-statement. 
The program does not execute any USE procedure specified for this file. 


8. Ifthe program does not specify an INVALID KEY phrase and does specify a USE 
procedure, the program executes the USE procedure. If the program does not 
specify a USE procedure, the program ends. 


The imperative-statement can be the NEXT SENTENCE phrase. 
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See Also 


e For information about naming a file, identifying its medium, specifying its 
organization, and so on, refer to “FILE-CONTROL Paragraph” in Section 5, 
“ENVIRONMENT DIVISION.” 


e For information about identifying the status of I/O operations, refer to “I/O Status” 
in Section 5, “ENVIRONMENT DIVISION.” 


e For information about opening a file, refer to “OPEN” earlier in this section. 


e For information on specifying procedures for J/O exception handling, refer to “USE” 
later in this section. 


RELEASE | 


The RELEASE statement transfers records to the initial phase of a sort operation. 


The general format of this statement is as follows: 


RELEASE record-name [ FROM identifier | 


Explanation of Format 


The RELEASE statement releases the record named by the record-name to the initial 
phase of a sort operation. 


A RELEASE statement can be used only in an INPUT PROCEDURE associated with 
a SORT statement for a file whose sort-merge file-description entry contains the 
record-name. 


The record-name must be the name of a logical record in the associated sort-merge __ 
file-description entry and can be qualified. The record-name and the identifier must not 
refer to the same storage area. 


If the FROM phrase is used, the contents of the identifier data area are moved to 
record-name. The contents of the record-name are released to the sort file. Moving 
takes place according to the rules specified for the MOVE statement. 


In a Unisys extension, the execution of a RELEASE statement does not affect the . 
contents or the accessibility of the record area. If the sort-merge file is named ina 
SAME RECORD AREA clause, the logical record is also available as a record of other 
files referenced in the same SAME RECORD AREA clause. When control passes from 
the INPUT PROCEDURE, the file consists of all records that were placed in it by the 
execution of RELEASE statements. 
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Note: IfaRELEASE statement is executed when there are more than 
32 PERFORM statements active, the RELEASE statement 
unconditionally causes the program to terminate with an INVALID 
INDEX error. This is a permanent restriction. 


See Also 


For information about the SORT statement, refer to “SORT” later in this section. 


RESET (Unisys Extension) 


The RESET statement is used to control communication between processes in an 
- asynchronous processing environment. 


The general format of this statement is as follows: 


RESET event-identifier-1 [ , event-identifier-2 ] ... 


Explanation of Format 


The RESET statement causes the event specified by event-identifier-1, event-identifier- 
‘2, and so on to be turned off. If the event is then tested, the condition returns the value 
FALSE. 


Event-identifiers must be one of the following: 
e Properly qualified and subscripted data-names with event usage specified 


e File or task attributes of type EVENT 


See Also 


For information about Inter-Program Communication, refer to “CAUSE (Unisys 
Extension)” earlier in this section. 


RESPOND (Unisys Extension) 


The RESPOND statement is used only with port files. This statement enables a 
program to accept or reject a request for a dialogue to be established or terminated. 


The program is prompted for a response through the CHANGEEVENT file 
attribute. The FILESTATE file attribute indicates the type of response for which 
the program is being prompted, for example, OPENRESPONSEPLEASE or 
CLOSERESPONSEPLEASE. — 
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The general format of this statement is as follows: 


ACCEPT-OPEN 
{ file-name} ... WITH RESPONSE-TYPE OF | RRT.oPE 
| | ACCEPT-CLOSE 
USING 
ASSOCIATED-DATA-LENGTH 


. OF esa 
integer 


ASSOCIATED-DATA 
ee } 
literal 


Explanation of Format 
The file-name identifies one or more port files. 


The WITH RESPONSE-TYPE phrase specifies the type of response. The response type 
must be consistent with the current state of the subfile. 


The ACCEPT-OPEN phrase accepts the request for a dialogue to be started. 

The REJECT-OPEN phrase rejects the request for a dialogue to be started. 

The ACCEPT-CLOSE phrase accepts the request for a dialogue to be ended. 

The USING option permits each of the USING clauses to be included one time only. 
The ASSOCIATED-DATA-LENGTH phrase specifies the number of characters to be 
sent. If you do not specify the length of the associated data and the associated data 

is a data item, your program uses the actual length of the data. If you do specify the 
length of the associated data, the length value must be less than or equal to the actual 
length of the data. An error results if the length specified is not a single-precision 
integer value. To use the ASSOCIATED-DATA-LENGTH phrase, you must specify the 
ASSOCIATED-DATA phrase with either an identifier or an undigit literal, but not a 
nonnumeric literal. 


The ASSOCIATED-DATA phrase transfers data to the correspcnaing subfile along with 
the request to close the dialogue. 


_ The integer must be a numeric literal. 


The identifier must name an elementary integer data item. 
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The identifier can be a group data item or an alphanumeric elementary data item. 


The literal can be a nonnumeric or undigit literal. 


General Rules 


You must use the RESERVE NETWORK clause in the SPECIAL-NAMES paragraph for 
the compiler to recognize the words RESPOND and RESPONSE-TYPE as keywords. 


The ACTUAL KEY clause specifies the subfile that is responding. If you do not code 
an ACTUAL KEY clause, the port file must contain a single subfile. If you are using 
multiple subfiles, do the following: 


1. Specify the total number of subfiles in your program by using the CHANGE 
ATTRIBUTE MAXSUBFILES TO VALUE attribute-value statement. 


2. Specify the subfile that is to respond by using the SELECT port-file ASSIGN TO 
PORT; ACTUAL KEY IS subfile-num 93 clause. 


3. Declare subfile-num and attribute-value in the WORKING-STORAGE SECTION. 


’ Table 9-14 shows the effects of the ACTUAL KEY clause value on the RESPOND verb. 


Table 9-14. Designating Subfiles to Respond 


Actual Key Value ; Explanation 


0 (zero) or none : Returns a BADSUBFILEINDEX run-time error in the 
' SUBFILEERROR file attribute. You are not allowed to 
respond to ail subfiles at once. 


Nonzero Responds with the specified subfile. 


Greater than the MAXSUBFILES Returns a BADSUBFILEINDEX run-time error in the 
value or a negative number. SUBFILERROR file attribute. 


The system returns a value that indicates the result of a RESPOND statement. You 

can access this value by including a SELECT file-name FILE STATUS IS data-name 
clause in your program. The operating system moves a value into the data-name storage 
area after the program performs the RESPOND statement. You can then use an IF 
statement to test the value of the data-name and take the desired action depending on 
the result. If you choose not to code actions for the result of a RESPOND statement, the 
system provides a default action for each result. 
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Table 9-15 shows the I/O status values and their meanings. 


Table 9-15. Values for RESPOND Statement Completion 


Value | Explanation 


00 ‘Control was returned to the program after the RESPOND statement 
completed correctly. In the case of a port file, the close operation might be 
pending. 


An error was detected while the file was being closed. 


+ Unisys extension 


Examples 


In the following examples, it is assumed that earlier in the program the port files were 
declared using an ACTUAL KEY clause to specify a subfile index and that the subfile 
index was set to a particular index. 


Example 9-23 accepts a request for an orderly close operation from the correspondent 
endpoint for the subfile of port file PORTFILE1. 


RESPOND PORTFILE1 WITH RESPONSE-TYPE OF ACCEPT-CLOSE. 

Example 9-23. Coding a RESPOND Statement for an Orderly Close Operation 
Example 9-24 accepts a request for a dialogue to be started on the subfile of port file 
PORTFILE1. 

RESPOND PORTFILE1 WITH RESPONSE-TYPE OF ACCEPT-OPEN. 
Example 9-24. Coding a RESPOND Statement That Requests a Dialogue 


Example 9-25 rejects an open dialogue request for the subfile on port file PORTFILE1. — 
The associated data "MYDATA" is sent with the response. 


RESPOND PORTFILE2 WITH RESPONSE-TYPE OF REJECT-OPEN 
USING ASSOCIATED-DATA OF “MYDATA". 


Example 9-25. Coding a RESPOND Statement That Rejects an Open Request 
Example 9-26 accepts an open dialogue request for the subfile on port file PORTFILE1. 


Twelve characters of associated data are sent with the response, beginning with the 
location pointed to by the ALPHANUM-ITEM item. 


RESPOND PORTFILE1 WITH RESPONSE-TYPE OF ACCEPT-OPEN 
USING ASSOCIATED-DATA-LENGTH 12 
ASSOCIATED-DATA OF ALPHANUM-ITEM. 


Example 9-26. Coding a RESPOND Statement That Uses Associated Data 
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Example 9-27 accepts open dialogue requests for the subfiles on the port files 
PORTFILE1 and PORTFILE2. . 


RESPOND PORTFILE1 PORTFILE2 WITH RESPONSE-TYPE OF ACCEPT-OPEN 
USING ASSOCIATED-DATA OF “MYDATA" 
USING ASSOCIATED-DATA-LENGTH NUMERIC-ITEM. 


Example 9-27. Coding a RESPOND Statement with Multiple Files 


See Also 
e For information about the RESERVE clause in the SPECIAL-NAMES paragraph, 
refer to Section 5, “ENVIRONMENT DIVISION.” | 


e For step-by-step information on coding port file applications, refer to the I/O 
Subsystem Programming Guide. 


e For references to file attributes, refer to the File Attributes Reference Manual. 


RETURN 


The RETURN statement causes the next record (in the order specified by the KEY 
clause in the SORT or the MERGE statement) to be transferred to the record area. 


The RETURN statement obtains either sorted records from the final phase of a sort 
operation or merged records during a merge operation. 


The general format of this statement is as follows: 


RETURN file-name RECORD [| INTO identifier | 


; AT END imperative-statement 
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Explanation of Format 


file-name 


The file-name must be described by a sort-merge file-description entry in the DATA 
DIVISION. 


A RETURN statement can be used only in the range of an output procedure associated 
with a SORT or a MERGE statement for the file-name. 
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INTO 


If the INTO phrase is specified, the current record is moved from the input area to 

the area specified by the identifier. The move takes place according to the rules for 

the MOVE statement without the CORRESPONDING phrase. The sending area is 
considered to be a group item with a fixed size equal to the maximum record size. The 
implied move does not occur if an At End condition exists. Any subscripting or indexing 
associated with the identifier is evaluated after the record is returned and immediately 
before it is moved to the data item. When the INTO phrase is used, the data is available 
in both the input record area and the data area associated with the identifier. 


The INTO phrase must not be used when the input file contains logical records of 
various sizes as indicated by the record descriptions. The storage area associated with 
the identifier and the record area associated with the file-name must not be the same 
storage area. 


AT END 


If no next logical record exists for the file when a So statement is executed, the 
At End condition occurs. 


When the At End condition occurs, no transfer of data to the record area takes place and 
the contents of the record area are undisturbed. After the At End condition occurs, 

the contents of the record area are still accessible. (This is a Unisys extension.) After 
execution of the imperative-statement in the AT END phrase, no RETURN statement 
can be executed as part of the current output procedure. 


The imperative-statement can be the NEXT SENTENCE phrase. 


General Rules 


When the logical records of a file are described with more than one record description, 
these records automatically share the same storage area. This sharing is equivalent to . 
an implicit redefinition of the area. The contents of any data items beyond the range of 
the current data record are undefined when the execution of the RETURN statement is 
complete: 


If records smaller than the maximum record size are released, the contents of the 
record area beyond the end of the released record are unpredictable when subsequently 
returned. In that case, you must account for the size of the logical record returned. 
(This is a Unisys extension.) : 


Note: Ifa RETURN statement is executed when there are more than 
32 PERFORM statements active, the RETURN statement. 
unconditionally causes the program to terminate with an INVALID 
INDEX error. This is a permanent restriction. 
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REWRITE 


The REWRITE statement replaces a logical record that exists in a mass-storage file. 


The REWRITE statement causes the value of the FILE STATUS data item associated 
with the file, if any, to be updated. — . 


. The general format of this statement is as follows: 


REWRITE record-name | SYNCHRONIZED | { FROM identifier | 


[; INVALID KEY imperative-statement | 
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Explanation of Format 


record-name and SYNCHRONIZED 


The record-name is the name of a logical record in the FILE SECTION of the DATA 
DIVISION and can be qualified. 


The file associated with the record-name must be open in the I-O mode when this 
statement is executed. 


The number of character positions in the record referenced by the record-name must 
equal the number of character positions in the record being replaced. 


Synchronization of all output records can be designated with the SYNCHRONIZE 

file attribute. Synchronization means that output must be written to the physical 

file before the program initiating the output can resume execution, thereby ensuring 
synchronization between logical and physical files. The SYNCHRONIZED clause enables 
you to override the synchronization specified by the file attribute for a specific output 
record. Synchronization is available for use by tape files and disk files with sequential 
organization only. 


FROM 

The FROM option makes the REWRITE statement operate like a MOVE statement 
followed by a WRITE statement. The move takes place according to the rules of the 
MOVE statement without the CORRESPONDING option. 


The record-name and the identifier must not refer to the same storage area. 
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INVALID KEY 


Refer to “Indexed I/O” later in this section for information about the Invalid Key 
condition. 


The imperative-statement can be the NEXT SENTENCE phrase. 


The execution of the REWRITE statement does not affect the contents or accessibility of 
the record area. (This is a Unisys extension.) 


The execution of a REWRITE statement with the FROM phrase is equivalent to the 
execution of the statement MOVE identifier TO record-name followed by the execution 
of the same REWRITE statement without the FROM phrase. 


Sequential |/O 


For files in the sequential access mode, the last I/O statement executed for the 
associated file before the execution of the REWRITE statement must have been a 
successfully executed READ statement. The I/O subsystem logically replaces the record 
that was accessed by the READ statement. 


For sequential files in the random or the dynamic access mode, the record to be 
rewritten is specified by the value of the actual key or the relative acs No prior reading 
of this record is required. 


Relative |/O 


For relative files in the random or the dynamic access mode, the record to be rewritten 
is specified by the value of the actual key or the relative key. No prior reading of this 
record is required. 


Indexed I/O 


The following rules apply to indexed I/O only: 


e For a file in the sequential access mode, the record to be replaced is specified by — 
the value contained in the prime record key. When the REWRITE statement is 
executed, the value contained in the prime-record-key data item of the record to be 
replaced must equal the value of the prime record key of the last record read from 
this file. 


e Fora file in the random or the dynamic access mode, the record to be replaced is 
specified by the prime- -record-key data item. 
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e The contents of alternate-record-key data items of the record being rewritten can 
differ from those in the record being replaced. The I/O subsystem uses the contents 
of the record key data items during the execution of the REWRITE statement so 
that subsequent access of the record can be made based on any of those specified 
record keys. 


e The Invalid Key condition exists under the following circumstances: 


- The access mode is sequential, and the value contained in the prime-record-key 
item of the record to be replaced does not equal the value of the prime record 
key of the last record read from this file. 


— The value contained in the prime-record-key data item does not equal that of any 
record stored in the file. 


- The value contained in an alternate-record-key data item for which a 
DUPLICATES clause is not specified equals that of a record already stored in 
the file. 


See Also 


e For information about the status of I/O operations, refer to “I/O Status” in 
Section 5, “ENVIRONMENT DIVISION.” 


e For information about opening a file in I-O mode, refer to “OPEN” in this section. 


RUN (Unisys Extension) 


The RUN statement enables a program to initiate another program as an independent, 
asynchronous task. Once a program is initiated by executing a RUN statement, it 
executes independently of the initiating program. 


The general format of this statement is as follows: 


RUN task-identifier WITH section-name 


[ USING arithmetic-expression-1 [ , arithmetic-expression-2 | ...] 


Explanation of Format 


The section-name must be the name of a USE procedure declared as EXTERNAL. 

Parameters must be passed by value, that is, contain a RECEIVED BY CONTENT 

clause. Only arithmetic values can be passed or received because only formal parameters 
- with arithmetic properties can be described in the syntax. 


The formal parameters to which the values of the arithmetic expressions are passed 


must be described as single-precision or double-precision 77-level items and must have a 
RECEIVED BY CONTENT clause. The compiler makes adjustments, if necessary, to 
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truncate double-precision values to single-precision values or extend single-precision 
values to double-precision values to ensure that the value passed has the same precision 
as the corresponding formal parameter. All values are passed with a scale of 0, 
regardless of the scale of the corresponding formal parameter, and can be passed as 
normalized values. 


The RUN statement creates an independent process, which does not share the resources 
of the initiator and can continue running after the termination of the initiator. 


An independent process must not be bound to a host program, nor can any of its data 
be declared with the GLOBAL or OWN phrases. Independent procedures (all the 
procedures of an independent process) must be compiled at the 02-level. 


SEARCH 


The SEARCH statement searches a table for a table element that satisfies the specified 
condition, and adjusts the associated index-name to indicate that table element. A 
SEARCH statement must be performed for each level of a table to be searched. 

The SEARCH statement has the following two formats: 


Format Explanation 


1 Performs a Serial Search on an unordered table. An unordered table is not 
arranged in a particular order. 


2 Performs a binary search on an ordered table. An ordered table is arranged in 
ascending or descending order. 


Format 1 


SEARCH identifier-1 | VARYING neacas } 


index-name-1 


[: AT END imperative-statement-1 | 


: WHEN condition-1 { 


imperative-statement-2 
NEXT SENTENCE 


tee 
: WHEN condition-2 ea ive-statement-3 


NEXT SENTENCE 
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Explanation of Format 1 


Format 1 of the SEARCH statement serially searches a table for a table element that 
satisfies the WHEN conditions. The search begins at the current index setting. — 


identifier-1 © 


Identifier-1 must not be subscripted or indexed, but its description must contain an 
OCCURS clause and an INDEXED BY clause. 


VARYING 
The VARYING option increments an index. 


Identifier-2, when specified, must be described as USAGE IS INDEX or as a numeric 
elementary item without positions to the right of the assumed decimal point. 


If the VARYING index-name-1 phrase is specified and if index-name-1 appears in the 


- INDEXED BY phrase of identifier-1, that index-name-1 is used for the search. If this 


is not the case, or if the VARYING identifier-2 phrase is specified, the first (or only) 
index-name given in the INDEXED BY phrase of identifier-1 is used for the search. In 


addition, the following operations occur: 


e Ifthe VARYING index-name-1 phrase is used, and if index-name-1 appears in the 
INDEXED BY phrase of another table entry, the occurrence number represented 
by index-name-1 is incremented by the same amount (and at the same time) as the 
occurrence number represented by the index-name associated with identifier-1. 


e Ifthe VARYING identifier-2 phrase is specified and if identifier-2 is an index 
data item, then the data item referenced by identifier-2 is incremented by the 
same amount (and at the same time) as the index associated with identifier-1. If 
identifier-2 is not an index data item, the data item referenced by identifier-2 is 
incremented by the value 1 at the same time the index referenced by the index-name 
associated with identifier-1 is incremented. 


AT END 


An AT END phrase can be used if the search ends and none of the conditions are 
satisfied. 


WHEN 


The WHEN phrase determines the ending condition for the search operation. You can 
specify a number of conditions for ending the search by using multiple WHEN phrases. 


Condition-1, condition-2, and so on can be any conditional expression. 
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Figure 9-3 shows a flowchart of the Format 1 SEARCH statement containing two 
WHEN phrases. 


Start 


Index setting: >At End* 
highest permissible 


occurence number 


imperative- 


statement-1 


imperative- we 
statement-2 


TRUE imperative 
condition-2 . statement-3 


FALSE 


Increment index-name 
for identifier-1 
(index-name-1 
if applicable) 


-* These operations are included 
only when specified in the 
SEARCH statement. 


** Control transfers to the 
% next executable sentence 
unless the imperative 
statement ends with a 
GO T0 statement. 


Increment index-name-1 
(for a different table) 
or identifier-2 


Figure 9-3. Flowchart for the SEARCH Statement Containing Two WHEN Phrases 


The following list describes the flow of contro] shown in Figure 9-3. 


e If, at the start of the execution of the SEARCH statement, the index-name 
associated with identifier-1 contains a value that corresponds to an occurrence 
number greater than the highest permissible occurrence number for 
identifier-1, the search ends immediately. If the AT END phrase is specified, the 
imperative-statement-1 is executed. Ifthe AT END phrase is not specified, control 
passes to the next executable sentence. 


e If, at the start of the execution of the SEARCH statement, the index-name 
associated with identifier-1 contains a value that corresponds to an occurrence 
‘number not greater than the highest permissible occurrence number for identifier-1, 
then the SEARCH statement operates by evaluating the conditions in their written 
order. The SEARCH statement makes use of index settings, wherever specified, to 
determine the occurrence of the items to be tested. 
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e Ifnone of the conditions is satisfied, the index-name for identifier-1 is incremented 
to refer to the next occurrence. The process is then repeated using the new 
index-name settings. If the new value of the index-name settings for identifier-1 
corresponds to a table element outside the permissible range of occurrence values, 
the search ends as indicated in the first bulleted item of this list. 


e If one of the conditions is satisfied on evaluation, the search ends immediately 
and the imperative-statement associated with that condition is executed. The 
index-name remains set at the occurrence that caused the condition to be satisfied. 


See Also 


The number of occurrences of identifier-1, the last of which is the highest permissible 
value, is discussed in Section 7, “DATA DIVISION.” 


Format 2 


SEARCH ALL identifier-1 [ ; AT END imperative-statement-1 | 


; WHEN 


IS EQUAL TO identifier-3 
data-name-1 { Q \ 


iS = literal-1 
7 arithmetic-expression-1 
condition-name-1 


literal-2 


data-name-2 { 
arithmetic-expression-2 


IS = 


' ¢ identifier-4 
IS EQUAL TO \ | 


condition-name-2. 


imperative-statement-2 
NEXT SENTENCE 
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Note: The required relational character = is not underlined to avoid 
confusion with other symbols. 


Explanation of Format 2 

The binary search operation searches an ordered, one-dimensional array. The data 
description of the table referred to in the SEARCH ALL statement must contain a 
Format 2 OCCURS clause with the INDEXED BY and KEY IS phrases. 


Identifier-1 must not be subscripted or indexed. 
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The index-name used for the search operation is the first (or only) index-name that 
appears in the INDEXED BY phrase of identifier-1. Any other index-names for 
identifier-1 remain unchanged. 


All referenced condition-names must be defined as having only a single value. The 
data-name associated with a condition-name must appear in the KEY clause of 
identifier-1. Data-name-1 and data-name-2 can be qualified. In addition, data-name-1 
and data-name-2 must be indexed by the first index-name associated with identifier-1 
along with other indexes or literals (as required) and must be referenced in the KEY 
clause of identifier-1. 


Identifier-3, identifier-4, or identifiers specified in arithmetic-expression-1 or 
arithmetic-expression-2 must not be referenced in the KEY clause of identifier-1, nor 
must they be indexed by the first index-name associated with identifier-1. 


When a data-name in the KEY clause of identifier-1 is referenced or when a 
condition-name associated with a data-name in the KEY clause of identifier-1 is 
referenced, all preceding data-names in the KEY clause of identifier-1 or their associated 
condition-names must also be referenced. 


The results of the SEARCH ALL statement are predictable only in the following cases: 


e The data in the table is ordered in the same manner as described in the 
ASCENDING/DESCENDING KEY clause associated with the description of 
identifier-1. _ 


e The contents of the keys referenced in the WHEN clause are sufficient to identify a 
unique table element. 


If the table is not ordered as specified, unpredictable results can be expected. 


When duplicates occur, the index indicates the occurrence of the duplicate closest to the 
beginning of the table. 


If any of the conditions specified in the WHEN clause cannot be satisfied for any setting 
of the index in the permitted range, control is passed to imperative-statement-1 of the 
AT END phrase, when specified, or to the next executable sentence when this phrase is 
not specified. In either case, the final setting of the index is the value corresponding to 
an occurrence number that is one greater than the last element of the table. 


General Rules for Format 1 and Format 2 


If all the conditions can be satisfied, the index indicates an occurrence that allows the 
conditions to be satisfied and control passes to imperative-statement-2. 


After execution of imperative-statement-1, imperative-statement-2, or imperative- 
statement-3 that does not end with a GO TO statement, control passes to the next 
executable sentence. In Format 1, if the VARYING phrase is not used, the index-name 
used for the search operation is the first (or only) index-name that appears in the 
INDEXED BY phrase of identifier-1. Any other index-names for identifier-1 remain 
unchanged. 
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If identifier-1 is a data item subordinate to a data item containing an OCCURS clause 
(providing for a multidimensional table), an index-name must be associated with each 
dimension of the table through the INDEXED BY phrase of the OCCURS clause. Only 
the setting of the index-name associated with identifier-1 (and the data item identifier-2 
or index-name-1, if present) is modified by the execution of the SEARCH statement. 

To search an entire multidimensional table, a SEARCH statement must be executed . 
several times. Before each execution of a SEARCH statement, SET statements need to 
be executed whenever index-names need to be adjusted to appropriate settings. 


See Also | 


e For information about conditional expressions, refer to “Conditional Expressions” in 
Section 8, “PROCEDURE DIVISION Concepts.” 


e For information about defining repeated data items, refer to “OCCURS Clause” in 
Section 7, “DATA DIVISION.” 


SEEK (Unisys Extension) 


The SEEK statement repositions a mass-storage file for subsequent sequential access. 


The general format of this statement is as follows: 


SEEK file-name RECORD 


SET 


9-116 


Explanation of Format 


For files specified with sequential access, the SEEK statement repositions the file so that 
a succeeding READ or WRITE statement accesses the record sought. 


‘The value of the ACTUAL KEY clause specified for the file-name is used as the ordinal 
’ number of the record sought. If the actual key contains a negative number or 0 (zero), 


the first record of the file is sought. The ACTUAL KEY clause must be specified in the 
FILE-CONTROL entry for the file-name. . 


The file-name must be the name of a mass-storage file of sequential organization. 


The execution of a SEEK statement does not cause the contents of the STATUS KEY 
data item to be updated. 


The SET statement establishes reference points for table handling operations by setting 
index-names associated with table elements. The SET statement can also be used to 
modify a file or a task attribute. 
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When a sending item and a receiving item in the same SET statement share a part, but 
not all, of their storage area, the result of the statement execution is undefined. 


The SET statement has the following four formats: 


Format Explanation 
1 Establishes an index value for table look-up operations 
2 Increments or decrements an index value 
3 Establishes the value of a table attribute 
4 Establishes the value of a file attribute 
Format 1 


identifier-3 
| ...LO ¢ index-name-3 
integer-1 


ser { 


identifier-1 \ | identifier-2 


index-name-1 , index-name-2 


Explanation of Format 1 


All references to index-name-1 and identifier-1 also apply to index-name-2 and 
identifier-2, respectively. 


If index-name-1 is specified, the value of the index after the execution of the SET 
statement should correspond to an occurrence number of an element in the associated 
table. : 


Index-name-1 can be set to any value, with the following restrictions: 


e If overflow occurs, the value in the index-name is left-truncated according to the 
arithmetic rules for a Size Error condition without a SIZE ERROR phrase. 


e When astatement is executed using the index-name to refer to a table element, the 
value contained in the index or produced by relative indexing must fall in the range 
specified by the OCCURS clause that defines the table. Otherwise, an abnormal 
termination of the program occurs. 


If index-name-3 is specified, the value of the index before execution of the SET 
statement should correspond to an occurrence number of an element in the associated 
table. 


Identifier-1 and identifier-3 must name either index data items or elementary items 
described as integers. 


Integer-1 can be signed and can be 0 (zero). 
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Table 9-16 shows the validity of various operand combinations of the SET statement. 


Table 9-16. Validity of Operands for the SET Statement 


‘Receiving Item Receiving Item Receiving Item 


Sending Item Integer Data Item Index-Name Index Data Item 
Integer literal ’ Not valid | Not valid 
Integer data item Not valid Not valid 


Index-name Valid Valid 


Index data item Not valid Valid 


In Format 1, the following actions occur: 


e Index-name-1 is set to a value that causes it to refer to the table element whose 
occurrence number corresponds to the table element referenced by index-name-3, 
identifier-3, or integer-1. If identifier-3 is an index data item or if index-name-3 is 
related to the same table as index-name-1, no conversion takes place. 


e If identifier-1 is an index data item, it can be set equal to either the contents of 
index-name-3 or to the contents of identifier-3, where identifier-3 is also an index 
data item. No conversion takes place in either case. 


e Ifidentifier-1 is not an index data item, it can be set only to an occurrence number 
that corresponds to the value of index-name-3. Neither identifier-3 nor integer-1 can 
be used in this case. 


e These actions can be repeated for index-name-2, identifier-2, and so on, if these — 
variables are specified. The value of index-name-3 or identifier-3 is used each time 
as it was at the beginning of the statement execution. Any subscripting or indexing 
associated with identifier-1 and so on is evaluated immediately before the value of 
the respective data item is changed. . 


Format 2 


SET index-name-4 [ , index-name-5 ].. 4 


UP BY identifier-4 
DOWN BY} |integer-2 


Explanation of Format 2 


All references to index-name-4 also apply to index-name-5. 
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Index-name-4 can be set to any value, with the following restrictions: 


e If overflow occurs, the value in the index-name is left-truncated according to the 
arithmetic rules for a Size Error condition without a SIZE ERROR phrase. 


e At execution of a statement using the index-name to refer to a table element, the 
value contained in the index or produced by relative indexing should fall in the 
range specified by the OCCURS clause that defines the table. A program can be 
abnormally terminated if the index addresses an item beyond the limits of the 
01-level record in which the table resides. Data can be retrieved from or modified 
within areas outside of the table (but still in the 01-level record in which the table 
resides) with unexpected results. 


e When integer-1 in a SET index-name-1 TO integer-1 statement exceeds the limits of 
the OCCURS clause to which index-name-1 refers, object code is generated for the 
SET statement that unconditionally terminates the program abnormally. 


In all other cases of the SET statement, the value to which index-name is set is not 
checked at execution time against the OCCURS clause for the table to which the 
index-name refers. 


You must ensure that the value to which index-name is set is appropriate, or you 
must ensure that the table associated with the index-name is correct. Unisys 
strongly discourages the use of inappropriate index.values to access parts of the 
01-level record outside the bounds of the table to which the index refers. 


The contents of index-name-4 are incremented using the UP BY phrase or decremented 
using the DOWN BY phrase by a value corresponding to the number of occurrences 
represented by the value of integer-2 or identifier-4. Thereafter, the incremental process © 
is repeated for index-name-5, and so on. For each repetition, the value of identifier-4 is 
used as it was at the beginning of the statement execution. 


If index-name-4 is specified, the value of the index both before and after the execution 
of the SET statement should correspond to an occurrence number of an element in the 


associated table. 


Index-names are considered to be related to a given table and are defined by 
specification in the INDEXED BY clause. 


Identifier-4 must be described as an elementary numeric integer. 


Integer-2 can be signed. 


See Also 


e For information on handling Size Error conditions, refer to “SIZE ERROR Phrase” 
in Section 8, “PROCEDURE DIVISION Concepts.” 
e For information on handling tables, refer to “Tables” in Section 6, “Data Concepts.” 


e For information about the validity of various operand combinations, refer to 
Table 9-16, “Validity of Operands for the SET Statement,” earlier in this section. 
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Format 3 


task-identifier 
SET MYSELF 


MYJOB 


([ subscript-1 , | task-attribute-name ) 


identifier-5 
literal-1 
arithmetic-expression-1 
VALUE 
[va 


} task-attribute-mnemonic 


Explanation of Format 3 


Note: F ormat 3 1s considered an obsolete element of COBOL74. The 
CHANGE statement is the preferred syntax. 


The task-attribute-name must be a system-name that defines a task attribute. 
Subscript-1 specifies the member of the task array that is affected, and can be an 
arithmetic expression. Subscript-1 is required when the task-identifier requires a 
subscript. 


Identifier-5 or literal-1 or the task-attribute-mnemonic must be consistent with the type 
of the task-attribute-name. 


A task-attribute-mnemonic is a name associated with a constant value for an attribute — 
that has a set number of predetermined possible values. 


The choice of identifier, literal, arithmetic-expression, or task-attribute-mnemonic 
depends on the attribute being set and its declared value. (This is a Unisys extension.) 


If a data-name has the same name as a task-attribute-mnemonic, the value assigned to 
the attribute is determined by the use of the optional word VALUE. If the word VALUE 
is present, the attribute is set to the value of the mnemonic. If the word VALUE is 
omitted, the attribute is set to the current value of the data-name. 
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Format 4 


SET file-name ( | subscript-2, | file-attribute-name ) 


identifier-6 

literal-2 

arithmetic-expression-2 
VALUE 

{vs 


} | mnemonic-attribute-value _ 


Explanation of Format 4 


Note: Format 4 is considered an obsolete element of COBOL74. The 
CHANGE statement is the preferred syntax. 


The file-name qualifies the file-attribute-name enclosed the required parentheses. 


Subscript-2 can be used only witha port file. The subscript can be an arithmetic- 
expression, and the value of the expression specifies the subfile of the file that is 
affected. 


- The choice of literal-2, arithmetic-expression-2, identifier-6, or the mnemonic-attribute- 
value depends on the type of the attribute and the static or dynamic nature of the value 
to which the attribute is to be set. . 


Mnemonic-attribute-values can be used as data-names or procedure-names in the 
program if they are not COBOL reserved words. (This is a Unisys extension.) 


Boolean or integer task attributes accept a numeric item or literal or the value associated 
with a mnemonic. If the value is not in the permissible range for the attribute specified, 
an error occurs at compilation time or at execution time. Task or file attributes of type 
POINTER accept alphanumeric items. 


If a data-name has the same name as a mnemonic-attribute-value, the value assigned to 
_ the attribute is determined by the use of the optional word VALUE. If the word VALUE 
— is present, the attribute is set to the value of the mnemonic. If the word VALUE is 
omitted, the attribute is set to the current value of the data-name. 


SORT 


The SORT statement creates a sort file by executing input procedures or by transferring 
records from another file. Records are sorted by the sort file using a set of specified 
keys. In the final phase of the sort operation, each record is made available 1 in sorted 
order to output procedures or to an output file. 
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SORT statements can appear anywhere except in the DECLARATIVES SECTION 
of the PROCEDURE DIVISION or in an INPUT PROCEDURE or an OUTPUT 
PROCEDURE clause associated with a SORT or a MERGE statement. 


The general format of the SORT statement is as follows: 


TAG-KEY 


SORT | rere 


PURGE 
\ file-name-1 | 


RUN ON ERROR 
END 


{ 0 lerscenen 


DESCENDIN a KEY {data-name-1} .. ? Se; 


[| COLLATING SEQUENCE IS alphabet-name | 


- : ; WORDS 
asony SIZE IS . eae ‘ | Guazactens | a 
ataname-2) | MODULES 


integer-2 \ reDUT \ 


DISK SIZE IS ¢- . 
| ae MODULES 


THROUGH 


IN PUT PROCEDURE IS section-name-1 | ‘Naat 


\ section-name-2 | 


LOCK 
USING file-name-2 | PURGE | en 
RELEASE 


THROUGH 


OUTPUT PROCEDURE JIS section-name-3 ine 


} section-name-4 | 


SAVE 

LOCK 
GIVING file-name-3 | RELEASE 

NO REWIND 

CRUNCH 
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Explanation of Format 


TAG-KEY (Unisys Extension) 


When the TAG-KEY option is used, sorting is performed on keys rather than on the 
entire record. The record numbers are placed in the sorted order in the GIVING file, 
which is restricted to records with a size of 8 DISPLAY digits. The TAG-KEY option 
prohibits the use of input and output procedures. 


TAG-SEARCH (Unisys Extension) 
When the TAG-SEARCH option is used, sorting is performed on keys rather than on the 
entire record. The records are then ordered in the GIVING file according to the sorted 
order of the record numbers. The TAG-SEARCH option prohibits the use of input and 
output procedures. 
Note: The file-name specified in the GIVING clause of a SORT 

TAG-SEARCH statement must not be the same as that specified in 

the USING clause. . 


The TAG-SEARCH option is not supported for tape input files or for multiple-file input. 


file-name-1 


File-name-1 must be described in a sort-merge file-description entry in the DATA 
DIVISION. 


ON ERROR (Unisys Extension) 


The ON ERROR option enables you to limit irrecoverable parity errors when input and 
output procedures are not present in a program. 


The PURGE phrase causes all records in a block that contains irrecoverable parity errors 
to be dropped; processing is continued after an ODT message is printed that gives the 
relative position in the file of the bad block. 


The RUN phrase causes the bad block to be used by the program and provides the same 
message as defined for the PURGE phrase. 


The END phrase causes program termination and is the default if no other phrase is 
specified. 


ASCENDING 
When the ASCENDING phrase is specified, the sorted sequence is from the lowest value 


of the contents of the data items identified by the KEY data-names to the highest value, 
according to the rules for comparison of operands in a relation condition. 
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DESCENDING 


When the DESCENDING phrase is specified, the sorted sequence is from the highest 
value of the contents of the data items identified by the KEY data-names to the lowest 
value, according to the rules for comparison of operands in a relation condition. 


Jata-name-1, data-name-2, and data-name 3 


Data-name-1, data-name-2, and data-name-3 are KEY data-names and are subject to the 
following rules: 


e The data items identified by KEY data-names must be described in records 
associated with file-name-1. 


e KEY data-names can be qualified. 
e The data items identified by KEY data-names must not be variable-length items. 


e If file-name-1 has more than one record description, then all the data items identified 
by the KEY data-names can be described in one of the record descriptions or in any 
combination of record descriptions. The KEY data-names in each record description 
need not be described again. 


e None of the data items identified by KEY data-names can be described by an entry 
that either contains an OCCURS clause or is subordinate to an entry that contains 
an OCCURS clause. . . 


e The data-names are listed from left to right in order of decreasing significance 
without regard to their division into KEY phrases. In the format, data-name-1 is the 
major key, data-name-2 is the next most significant key, and so on. 


COLLATING SEQUENCE 


The collating sequence that applies to the comparison of the nonnumeric key data items 
specified is determined in the following order of precedence: 


1. The collating sequence established by the COLLATING SEQUENCE phrase, if 
‘specified, in the SORT statement 


2. The collating sequence established as the program-collating sequence 


MEMORY SIZE (Unisys Extension) 


The MEMORY SIZE option is a guideline for allocating the SORT memory area and 
takes precedence over the same clause in the OBJECT-COMPUTER paragraph. This 
option can be allocated as MODULES, WORDS, or CHARACTERS. If the MEMORY 
SIZE option is not specified, either in the OBJECT-COMPUTER paragraph or in the 
SORT statement, a default value of 12,000 words is assumed. If the number of records 
to be sorted varies from run to run, the memory size can be allocated by specifying 
data-name-5. 
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DISK SIZE (Unisvs Extension) 


The DISK SIZE option is a guideline for allocating the SORT disk area and takes 
precedence over the same clause in the OBJECT-COMPUTER paragraph. This option 
can be allocated as WORDS or MODULES. If the DISK SIZE option is not specified, 
either in the OBJECT-COMPUTER paragraph or in the SORT statement, a default 
value of 900,000 words is assumed. One module of disk is equivalent to 1.8 million words 
of disk. If the number of records to be sorted varies from run to run, the disk size can be 
allocated by specifying data-name-6. 


INPUT PROCEDURE 


The input procedure must consist of one or more procedures that appear contiguously in 
a source program and do not form a part of any output procedure. To transfer records to 
the file referenced by file-name-1, the INPUT PROCEDURE clause must include at least 
one RELEASE statement. Control must not be passed to the input procedure except 
when a related SORT statement is being executed. The input procedure can include any 
sections needed to select, create, or modify records. The restrictions on the procedural 
statements in the INPUT PROCEDURE clause are as follows: 


e The INPUT PROCEDURE clause must not contain any SORT or MERGE 
- statements. 


e The remainder of the PROCEDURE DIVISION must not contain any transfers 
of control to points inside the input procedure; ALTER, GO TO, and PERFORM 
statements in the remainder of the PROCEDURE DIVISION must not refer to 
section-names in the INPUT PROCEDURE clause. Also, while the input procedure 
can perform a program portion outside of itself, control must always return to the 
input procedure. 


If an input procedure is specified, control is passed to the input procedure before 
file-name-1 is sequenced by the SORT statement. The compiler inserts a one-time-only 
return mechanism at the end of the last section in the input procedure; an EXIT 
statement cannot be used to return control to the SORT statement. Control then passes 
to the last statement in the INPUT PROCEDURE clause and the records that have been 
released to file-name-1 are sorted. 


In the input procedure, excessive use of GO TO statements to transfer control out of 
blocks being executed by PERFORM statements can cause the program to fault with an 
Invalid Index condition at the RETURN statement. 

The words THRU and THROUGH are equivalent. 


Section-name-1 represents the name of an input procedure. 
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USING 


If the USING phrase is specified, all records in file-name-2 are transferred automatically 
to file-name-1. At execution of the SORT statement, file-name-2 must not be open. The 
SORT statement automatically does the following: 

e Starts the processing of file-name-2 

e Makes the logical records for file-name-2 available 

e. Ends the processing of file-name-2 

These implicit functions are performed so that any associated USE procedures are 
executed. Also, the SORT statement automatically and implicitly moves the records 


from the file area of file-name-2 to the file area of file-name-1, and releases records to the | 
initial phase of the sort operation. 


file-name-2 and file-name-3 


File-name-2 and file-name-3 must be described in a file-description entry (not a 


' sort-merge file-description entry) in the DATA DIVISION. The actual size of the logical 


records described for file-name-2, file-name-3, and file-name-4 must equal the actual size 
of the logical records described for file-name-1. 


LOCK, PURGE, and RELEASE (Unisys Extension) 


The LOCK, PURGE, and RELEASE options can be used to specify the type of file close 
operation for the USING files, file-name-2, file-name-3, and so on. The TAG-SEARCH 
option prohibits the use of the close options LOCK and PURGE on the USING file. 


OUTPUT PROCEDURE 


The output procedure must consist of one or more procedures that appear contiguously 
in a source program and do not form part of any input procedure. To make sorted 
records available for processing, the OUTPUT PROCEDURE clause must include at 
least one RETURN statement. Control must not be passed to the output procedure, 
except when a related SORT statement is being executed. The output procedure can 
consist of any procedures needed to select, modify, or copy the records that are being 
returned, one at a time and in sorted order, from the sort file. The restrictions on the 
procedural statements in the OUTPUT PROCEDURE clause are as follows: 


e The OUTPUT PROCEDURE clause must not contain any SORT or MERGE 
statement. 


© The remainder of the PROCEDURE DIVISION must not contain any transfers of 
control to points inside the output procedure; ALTER, GO TO, and PERFORM 
statements in the remainder of the PROCEDURE DIVISION cannot refer to 
section-names in the OUTPUT PROCEDURE clause. Also, while an output 
procedure can perform a program portion outside of itself, control must always 
return to the output procedure. 


Tfan output procedure is specified, control passes to the output procedure after - 


file-name-1 has been sequenced by the SORT statement. The compiler inserts a return 
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mechanism at the end of the last section in the output procedure. When control passes 
the last statement in the OUTPUT PROCEDURE clause, the return mechanism 
provides for termination of the sort operation and then passes control to the next 
executable statement after the SORT statement. Before entering the output procedure, 
the sort procedure reaches a point at which it can select the next record in sorted order, 
when requested. The RETURN statements in the OUTPUT PROCEDURE clause are 
the requests for the next record. 


In the output procedure, excessive use of GO TO statements to transfer control out of 
blocks being executed by PERFORM statements can cause the program to fault with an 
Invalid Index condition at the RETURN statement. 


Section-name-3 represents the name of an output procedure. 


GIVING 


If the GIVING phrase is specified, all sorted records in file-name-1 are automatically 
written on file-name-3 as the implied output procedure for this SORT statement. At 
execution of the SORT statement, file-name-3 must not be open. The SORT statement 
automatically does the following: 


e Starts the processing of file-name-3 | 

e Releases the logical records to file-name-3 

e Ends the processing of file-name-3 

The terminating function is performed as if a CLOSE statement without optional 
phrases had been executed for the file. These implicit functions are performed so that 
any associated USE procedures are executed. Also, the SORT statement automatically 


and implicitly returns the sorted records from the final phase of the sort operation and 
moves the records from the file area for file-name-1 to the file area for file-name-3. 


The SAVE, LOCK, PURGE, RELEASE, NO REWIND, and CRUNCH options can be 
used to specify the type of file close operation for the GIVING file, file-name-4, and so on. 


See Also 


For information on the SAVE, LOCK, PURGE, RELEASE, NO REWIND, and 
CRUNCH options for closing files, refer to “CLOSE” earlier in this section. 


Examples 


In Example 9-28, the files defined by the FD entries are opened before the SORT 
statement is executed. The SORT statement sets the sorting mechanism in motion 

by transferring control to the input procedure. The files can be opened with the input 
procedure, but the input file must not be opened more than once or closed before input is 
completed. 


Sorting is conducted on an ascending key. Note that the key identifiers are defined i in 
the sort file WORK-ING, not the input file TO-BE-SORTED. 


8600 0296-000 - | | 9-127 


PROCEDURE DIVISION Statements 


9-128 


The input procedure is completed when the entire input file has been transferred to . 
the sort file. The sort mechanism then transfers control to the output procedure, 
and records are written on the file AFTER-THE-SORT in the order specified by the 
key parameters. The sorted records are then listed after the sort operation has been 
completed. 


IDENTIFICATION DIVISION. 


* 


*THIS SORT PROGRAM EXAMPLE SHOWS HOW THE "INPUT PROCEDURE IS" 
*AND "OUTPUT PROCEDURE IS" OPTIONS WORK. 


* 


ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. B79@@. 
OBJECT-COMPUTER. B79Q0. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 


SELECT TO-BE~SORTED ASSIGN TO DISK. 


~ SELECT AFTER-THE-SORT ASSIGN TO DISK. 


SELECT WORK-ING ASSIGN TO SORT. 
SELECT FOR-THE~PRINTER ASSIGN TO PRINTER. 


DATA DIVISION. 
FILE SECTION. 


FD 


61. 


FD 
G1 
SD 


G1 


FD 


G1 


TO-BE-SORTED 

LABEL RECORDS ARE OMITTED 
DATA RECORD IS A-FILE. 

A-FILE. 

G2 1-ACCOUNT PICTURE IS X(4). 
@2 1-TYPE PICTURE IS X. 


-@2 1-AREA PICTURE IS XXX. 


92 1-BODY PICTURE IS X(72). 
AFTER-THE-SORT . 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS B-FILE. 
B-FILE PIC IS X(8@). 
WORK-ING 


DATA RECORD IS C-FILE. 


C-FILE. 

@2 3-ACCOUNT PIC IS X(4). 
@2 3-TYPE PIC IS X. 

@2 3-AREA PIC IS XXX. 

@2 3-BODY PIC IS X(72). 
FOR-THE-PRINTER 

LABEL RECORDS ARE OMITTED 
DATA RECORD IS D-FILE. 
D-FILE PIC IS X(80). 


PROCEDURE DIVISION. 


* 


*FILES DEFINED BY FD ENTRIES ARE OPENED. 


* 


Example 9-28. Sort Program Using INPUT PROCEDURE IS and OUTPUT 


PROCEDURE IS Options 
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OPENING SECTION. 


* 


OPENER. 
OPEN INPUT TO-BE-SORTED. 
OPEN OUTPUT AFTER-THE-SORT FOR-THE-PRINTER. 


*SORTING BEGINS AS CONTROL IS PASSED TO THE INPUT PROCEDURE. 
*SORTING IS CONDUCTED ON 3 ASCENDING KEYS DEFINED IN WORK-ING. 
*THE INPUT PROCEDURE IS COMPLETED WHEN THE ENTIRE INPUT FILE IS 
*TRANSFERRED TO THE SORT FILE. 


* 


*THE SORT FILE THEN TRANSFERS CONTROL TO THE OUTPUT PROCEDURE, AND 
*RECORDS ARE WRITTEN ON THE FILE AFTER-THE-SORT IN THE ORDER . 
*SPECIFIED BY THE KEY PARAMETERS. THE SORTED RECORDS ARE THEN 
*LISTED AFTER THE SORT FUNCTION IS DONE. 


* 


A-SORT SECTION. 
Pl. SORT WORK-ING ON ASCENDING KEY 3-ACCOUNT 3-TYPE 3-AREA 
INPUT PROCEDURE IS B-SORT THROUGH B1-SORT 
OUTPUT PROCEDURE IS C-SORT THROUGH C1-SORT. 
GO TO OK-PRINT. 
B-SORT SECTION. 
P2. READ TO-BE-SORTED AT END GO TO B1-SORT. 
RELEASE C-FILE FROM A-FILE. 
GO TO B-SORT. 
B1-SORT SECTION. 
P3. CLOSE TO-BE-SORTED. 


~C-SORT SECTION. 


P4. RETURN WORK-ING RECORD INTO B-FILE AT END GO TO C1-SORT. 
WRITE B-FILE. 
GO TO C-SORT. 
C1-SORT SECTION. 
P5. CLOSE AFTER-THE-SORT. 
OK-PRINT SECTION. 
P6. OPEN INPUT AFTER-THE-SORT. 
A-LOOP SECTION. 
P7. READ AFTER-THE-SORT AT END GO TO A-1-MOVE. 
PERFORM A-MOVE. ad 
WRITE D-FILE. 
GO TO A-LOOP. 
A-MOVE SECTION. 
P8. MOVE B-FILE TO D-FILE. 
A-1-MOVE SECTION. 
P9. EXIT. 
ALL-DONE SECTION. | 
PA. CLOSE AFTER-THE-SORT FOR-THE-PRINTER. 
. STOP RUN. 


Example 9-28. Sort Program Using INPUT PROCEDURE IS and OUTPUT 
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START 


The START statement positions records logically in a relative or an indexed file for 
sequential record retrieval. 


The general format of this statement is as follows: 


IS EQUAL TO 
IS = 


START file-name | KEY 1 eee data-name 


Is > 
IS NOT LESS THAN 
IS NOT < _ 


[ ; INVALID KEY imperative-statement | 


9-130 


Note: The required'relational characters >, <, and = are not underlined 
to avoid confusion with other symbols. 


Explanation of Format 


file-name 
The file-name must be the name of a file with sequential or dynamic access. 


The file-name must be open in the INPUT or I-O mode when the START statement is 
executed. 


Execution of the START statement causes the value of the FILE STATUS data item, if 
any, associated with the file-name to be updated. 


KEY 


For relative I/O, any specified data-name must be the data item specified in the 
RELATIVE KEY phrase of the associated file-control entry. 


For indexed I/O, if the KEY phrase is specified, the data-name can reference either of the 
following: 


e A data item specified as a record key associated with the file-name 


e Any alphanumeric data item subordinate to the data item specified as a record key, 
. and associated with a file-name with a leftmost character position corresponding to 
the leftmost character position of that record key data item 


If the KEY phrase is not specified, the relational operator IS EQUAL TO is implied. 
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If execution of the START statement is unsuccessful, the reference key is undefined. 


The data-name can be qualified. 


imperative-statement 


The imperative-statement can be the NEXT SENTENCE phrase. 


See Also 


e For information about the status of I/O operations, refer to “I/O Status” in 
Section 5, “ENVIRONMENT DIVISION.” 


e For information about the INVALID KEY phrase, refer to “READ” earlier in this 
section. 


Relative |/O Comparison 


The type of comparison specified by the relational operator in the KEY phrase occurs 
between a key associated with a record in the file referenced by the file-name and the 
data item referenced by the RELATIVE KEY clause associated with the file-name. The 
following occurs during a relative I/O comparison: 


e The current-record pointer is positioned to the first logical record in the file with a 
key that satisfies the comparison. 


e Ifthe comparison is not satisfied by any record in the file, then an Invalid Key 
condition exists, execution of the START statement is unsuccessful, and the position 
of the current-record pointer is undefined. 


Indexed 1/0 Comparison 


The type of comparison specified by the relational operator in the KEY phrase occurs 
between a key associated with a record in the file referenced by the file-name and a 
data item referenced by the data-name. If the file-name references an indexed file 

and the operands are of unequal size, comparison proceeds as if the longer operand 
were truncated on the right so that its length equals that of the shorter operand. All 
other nonnumeric comparison rules apply, except that the presence of the PROGRAM 
COLLATING SEQUENCE clause does not affect the comparison. The following occurs 
in an indexed I/O comparison: 


e The current record pointer is positioned to the first logical record currently existing 
in the file that has a key that satisfies the comparison. 


e Ifthe comparison is not satisfied by any record in the file, then an Invalid Key 
condition exists, a value of 23 is returned to the status key, execution of the 
START statement is unsuccessful, and the position of the current record pointer is 
undefined. 


_If the KEY phrase is not specified, the comparison previously described uses the data 
item referenced in the RECORD KEY clause associated with the file-name. 
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Reference Key Use 


When the START statement has successfully executed, a reference key is established . 
and used in subsequent Format 3 READ statements as follows: 


e Ifthe KEY phrase is not specified, the prime record key specified for the file-name 
becomes the reference key. 


e Ifthe KEY phrase is specified and the data-name is specified as a record key for 
file-name, that record key becomes the reference key. 


e Ifthe KEY phrase is specified and the data-name is not specified as a record key for 
the file-name, the record key with the leftmost character position corresponding to 
the leftmost character position of the data item specified by the data-name becomes 
the reference key. 


STOP 


The STOP statement permanently ends or temporarily suspends the object program. 


The general format of this statement is as follows: 


STOP { 


RUN \ 
literal 


Explanation of Format 


STOP RUN 


When the STOP RUN statement is executed, all open files are closed, all storage areas 
are returned to the system, and the program is terminated normally. If the program is 
linked to other programs as a run-unit through the standard COBOL Inter-Program 
Communication (IPC) mechanism, or if the program is operating as a library, these 
programs are also ended. 


STOP literal 


If the STOP literal statement is specified, the literal is displayed to the operator. 
When the operator responds with an OK response for the program, the object program 
continues with the next executable statement. 


If the program is run from CANDE, the literal is also displayed on the remote terminal. 
The OK response can also be entered from the terminal. For more information, refer to 
the A Series CANDE Operations Reference Manual. 


The literal can be numeric or nonnumeric, and can be any figurative constant that does 
not include the optional word ALL. 
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If the literal is numeric, it must be an unsigned integer. 


A STOP literal statement in a called program that is part of an IPC run-unit is ignored 
at execution time. 


See Also 


Execution of the STOP RUN statement in a called program is described under “CALL” 
in this section. 


STRING 


The STRING statement joins several data items to form one data item. This process is 
termed concatenation. 


The general format of this statement is as follows: 


identifier-1 \ | (eerie \ 


STRING 
{ literal-1 literal-2 


FO { identifier-9 \ 
~~ { integer-1 
. identifier-3 
DELIMITED BY | literal-3 
| SIZE 


identifier-4 \ , identifier-5 
’ | literal-4 , literal-5 


FOR { a } 
——~_| integer-2 


identifier-6 
DELIMITED BY literal-6 
SIZE 


INTO identifier-7 [ WITH POINTER identifier-8 | 


[ ; ON OVERFLOW imperative-statement | 
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Explanation of Format 


All references to identifier-1, identifier-2, identifier-3, identifier-9, literal-1, literal-2, 
literal-3, and integer-1 apply. equally to identifier-4, identifier-5, identifier-6, identifier-10, 
literal-4, literal-5, literal-6, and integer-2, respectively. (Identifier-9, integer-1, 
identifier-10, and integer-2 are Unisys extensions.) 


All literals must be described as nonnumeric literals, and all identifiers except 
identifier-8, identifier-9, and identifier-10 must be described implicitly or explicitly as 
USAGE IS DISPLAY. 


When a sending item and a receiving item in the same STRING statement share a 
part, but not all, of their storage areas, the result of the execution of the statement is 


undefined. 


identifier-1 or literal-1 

Identifier-1 or literal-1 and any repetition represent the sending items. 

Characters from literal-1, literal-2 or from the contents of identifier-1, identifier-2 are 
transferred to identifier-7 under the rules for alphanumeric-to-alphanumeric moves, 
except that no space-filling is provided. _ 


Literal-1 can be any figurative constant that does not include the optional word ALL. 


If identifier-1 or any repetition is an elementary numeric data item, then the data item 
must be described as an integer. 


When a figurative constant is specified as literal-1, it refers to an implicit 1-character 
data item with USAGE IS DISPLAY. 


FOR (Unisys Extension) 

If the FOR phrase is specified, the contents of identifier-1, identifier-2 or the contents of 
literal-1, literal-2 are transferred to identifier-7 in the sequence specified in the STRING 
statement. This sequence begins with the leftmost character and continuing from left to 
right until the end of identifier-7 is reached, or until the number of characters specified 
by integer-1 or by the contents of identifier-9 are moved. 


Identifier-9 and identifier-10 must represent data items that are elementary numeric 
integers. . 


Integer-1 and identifier-9 indicate the number of characters to be moved. 


DELIMITED BY identifier-3 or literal-3 


This phrase specifies the characters that delimit the end of the data item to be joined. 


The contents of identifier-1, identifier-2 or the contents of literal-1, literal-2 are 


transferred to identifier-7 in the sequence specified in the STRING statement. This 
sequence begins with the leftmost character and continuing from left to right until 
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the end of the data item is reached, or until the characters specified by literal-3 or by 
the contents of identifier-3 are encountered. The characters specified by literal-3 or 
identifier-3 are not transferred. 


When a figurative constant is used as a delimiter, it stands for a single-character, 
nonnumeric literal. 


When a figurative constant is specified as literal-3, it refers to an implicit 1-character 
data item with display usage. Literal-3 can be any figurative constant that does not 
include the optional word ALL. 


Literal-3 or identifier-3 indicates the characters delimiting the move. 


DELIMITED BY SIZE 


If the SIZE phrase is used, the complete data item defined by identifiers or literals is 
moved. 


The contents of literal-1, literal-2 or the contents of identifier-1, identifier-2 are 


transferred (in the sequence specified in the STRING statement) to identifier-7 until all 
the data has been transferred or until the end of identifier-7 is reached. 


INTO 
Identifier-7 represents the receiving item. 


When characters are transferred to identifier-7, they are moved in the following two 
ways: 


e Asif the characters were moved one at a time from the source into the character 


position of the data item referenced by identifier-7 and designated by the value 
associated with identifier-8. . 


e As if identifier-8 were increased by one prior to the movement of the next character. 
The value associated with identifier-8 is changed during execution of the STRING 
statement only as specified in the previous paragraph. 


At the end of the execution of the STRING statement, only the portion of identifier-7 
that was referenced during the STRING statement’s execution is changed. 


Identifier-7 must represent an alphanumeric data item without editing symbols or the 
JUSTIFIED clause. 


POINTER 
This option indicates the starting position for data to be moved to the receiving field. 
The initial value of identifier-8 must not be less than 1. 9 


Identifier-8 must represent an elementary-numeric-integer data item large enough to 
- contain a value equal to the size of the area referenced by identifier-7 plus 1. 
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If, at any time during or after the STRING-statement initialization but beforethe 
completion of the STRING statement execution, the value of identifier-8 is less than 1 or 
exceeds the number of character positions in identifier-7, no further data is transferred 
to identifier-7. The imperative-statement in the ON OVERFLOW ener is then 
executed, if specified. 


If the POINTER phrase is not specified, the following overflow rules apply as if 
identifier-8 were specified with an initial value of 1. 


ON OVERFLOW 


An overflow condition occurs when the receiving field is full and the sending field still has 
characters to be moved, or when the pointer does not specify a valid value. 


If the ON OVERFLOW phrase is not specified when the overflow conditions are 
encountered, control is transferred to the next executable statement. 


The imperative-statement can be the NEXT SENTENCE phrase. 


SUBTRACT 


The SUBTRACT statement subtracts one numeric data item or the sum of two or more 
numeric data items from one or more items, and sets the values of one or more items 
equal to the results. 


The SUBTRACT statement has the following three formats: 


Format Explanation 


1 Adds the operands preceding the word FROM and subtracts the total from the 
current value of identifier-m; the results of the subtraction are stored in 
identifier-n. This process is repeated for each operand following the word FROM. 


2 Adds the operands preceding the word FROM and subtracts the total from 
identifier-m. The result is stored in identifier-n. 
3 Subtracts corresponding items. 
- Format 1 


SUBTRACT { 


=e | ioe 
literal-1 ’ Uiteral-2 ; 


FROM identifier-m [ ROUNDED ] |, identifier-n [ ROUNDED ] ]... 


[ ; ON SIZE ERROR imperative-statement | 
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Explanation of Format 1 

In Format 1, all literals or identifiers preceding the word FROM are added together. 
This total is subtracted from the current value of identifier-m. The result is immediately 
stored in identifier-m; the process is then repeated for each operand following the word 
FROM. 

Each identifier must refer to a numeric elementary item. 


Each literal must be a numeric literal. 


The imperative-statement can be the NEXT SENTENCE phrase. 


Format 2 


FROM irearena 


literal-m 


‘SUBTRACT { 


identifier-1} [, identifier-2 
literal-1 , literal-2 


GIVING identifier-n [ROUNDED] |, identifier-o [ROUNDED]]... 


[; ON SIZE ERROR imperative-statement| 


Explanation of Format 2 

In Format 2, all literals or identifiers preceding the word FROM are added together, 
the sum is subtracted from literal-m or identifier-m, and the result of the subtraction i is 
stored as the new value of identifier-n, identifier-o, and so on. 


Bach identifier must refer to a numeric elementary item. 


Each identifier following the word GIVING must refer to either an elementary numeric 
item or an elementary numeric-edited item. 


Each literal must be a numeric literal. 
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SUBTRACT { 


Format 3 


CORRESPONDING 


CORR \ identifier-1 


FROM identifier-2 [ ROUNDED |] 


[ ; ON SIZE ERROR imperative-statement | 
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Explanation of Format 3 


If Format 3 is used, data items in identifier-1 are subtracted from, and stored into, 
corresponding data items in identifier-2. | 


Each identifier must refer to a group item. 
CORR is an abbreviation for CORRESPONDING. 


The imperative-statement can be the NEXT SENTENCE phrase. 


General Rules 


When a sending item and a receiving item in the same SUBTRACT statement share a 
part, but not all, of their storage areas, the result of the execution of the statement is 
undefined. 


Note that unpredictable results occur in a Format 1 SUBTRACT statement if the same 
operand appears more than once in the list of operands that follows the word FROM in 
the statement. For example, assuming X contains the value 9 and Y contains the value 2, 
the value of X is 7 instead of 3 after execution of the following statement: 


SUBTRACT Y FROM X, X, X 


See Also 


e For information on the format rules for arithmetic statements, refer to “Common 
Rules for Arithmetic Statements” in Section 8, “PROCEDURE DIVISION 
Concepts.” 


e For information about corresponding fields in group items, refer to . 
“CORRESPONDING Phrase” in Section 8, “PROCEDURE DIVISION Concepts.” 


e For information about storing the result of the subtraction in more than one field, | 
refer to “Calculating Multiple Results with One Arithmetic Statement” in Section 8, 
“PROCEDURE DIVISION Concepts.” 
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e For information on truncation and rounding of results, refer to “ROUNDED Phrase” 
in Section 8, “PROCEDURE DIVISION Concepts.” 


e For information on handling Size Error conditions, refer to “SIZE ERROR Phrase” 
in Section 8, “PROCEDURE DIVISION Concepts.” 


UNLOCK (Unisys Extension) 


The UNLOCK statement is used in an asynchronous processing environment in 
conjunction with the LOCK statement. 


The general format of this statement is as follows: 


UNLOCK { 


lock-identifier \ 
event-identifier 


Explanation of Format 


The UNLOCK statement acts as the logical opposite of the LOCK statement by 
releasing the imposed common resource restriction. 


The system intrinsic LIBERATE function is invoked by the UNLOCK statement. 


Lock-identifiers must be declared with the phrase USAGE IS LOCK. Event-identifiers 
must be declared with the phrase USAGE IS EVENT or event-valued task attributes. 


See Also 


For information about locking common storage areas and testing for a locked condition, 
refer to “LOCK (Unisys Extension)” earlier in this section. 


UNSTRING 


The UNSTRING statement separates contiguous data in a sending field and places it in 
multiple receiving fields. 


When a sending item and a receiving item in the same UNSTRING statement share a 


part, but not all, of their storage areas, the result of the execution of the statement is 
undefined. 
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~The UNSTRING statement has the following two formats: 


Format Explanation 
1 Separates one field into a number of fields. A delimiter specifies the location at 
which to separate the field. 
2 Specifies a number of consecutive characters in a sending field to be moved to a 
receiving field. 
Format 1 


DELIMITED BY [ALL] { 


identifier-2 } 
literal-1 
identifier-3 \ 
literal-2 —s 


UNSTRING identifier-1 
OR [ALL] { 


INTO identifier-4 [, DELIMITER IN identifier-5] [, COUNT IN identifier-6] 
[, identifier-7 [, DELIMITER IN identifier-8] [, COUNT IN identifier-9]] ... 
[, WITH POINTER identifier-10] [, TALLYING IN identifier-11] 


[; ON OVERFLOW imperative-statement | 


Explanation of Format 1 
Each literal must be a nonnumeric literal and can be any figurative constant that does 
not include the optional word ALL. Identifier-1, identifier-2, identifier-3, identifier-5, and 


identifier-8 must be described as alphanumeric data items. 


Identifier-6, identifier-9, identifier-10, and identifier-11 must be described as 
elementary-numeric-integer data items. 


All references in this discussion to identifier-2, literal-1, identifier-4, identifier-5, 


and identifier-6 apply equally to identifier-3, literal-2, identifier-7, identifier-8, and 
identifier-9, respectively. (Integer-2 is a Unisys extension.) 


identifier-1 


Identifier-1 represents the sending area. 
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DELIMITED BY 


Literal-1 or identifier-2 specifies a delimiter. 


ALL 
When the optional ALL phrase is specified, one or more contiguous occurrences of the 


delimiter are considered to be one delimiter (for matching purposes), but only one of 
these occurrences is moved to the receiving area for delimiters. 


literal-1 or identifier-2 
Each literal-1 or identifier-2 represents one delimiter. When a delimiter contains two 
or more characters, all of the characters must be present in contiguous positions of the 


sending item, in the order given, to be recognized as a delimiter. 


- When the program encounters two contiguous delimiters, the current receiving area is 
either space- or zero-filled, according to the description of the receiving area. 


OR 

When two or more delimiters are specified in the DELIMITED BY phrase, an Or 
condition exists between them. Each delimiter is compared to the sending field. Ifa 
match occurs, multiple characters in the sending field are considered to be a single 
delimiter. No characters in the sending field can be considered a part of more than one 
delimiter. | 


Each delimiter is applied to the sending field in the sequence specified in the 
UNSTRING statement. 


When a figurative constant is used as a delimiter, it stands for a single-character, 
nonnumeric literal. 


INTO 
Identifier-4 represents the data receiving area and is described as USAGE IS DISPLAY. 
Identifier-4 can be described as one of the following: 


° Alphabetic (except that the symbol B cannot be used in the PICTURE character 


string) 
e Alphanumeric (except that the symbol P cannot be used in the PICTURE character 
string) 
e Numeric (except that the symbol P cannot be used in the PICTURE character 
~ string) 
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DELIMITER IN 


If several delimiters are used to split a field, the DELIMITED IN option can be used to 
identify the delimiter that unstrung the field. 


Identifier-5 represents the receiving area for delimiters. 


The DELIMITER IN phrase can be specified only if the DELIMITED BY phrase is 
specified. 


COUNT IN 

This phrase counts the number of characters in each field. 

Identifier-6 represents the number of characters in identifier-1 that are isolated by 
the delimiters for the move to identifier-4. This value does not include the number of 
delimiter characters. 


The COUNT IN phrase can be specified only if the DELIMITED BY phrase is specified. 


POINTER 
Identifier-10 must be described as an elementary-numeric-integer data item. 


The initialization of the contents of the data items associated with the POINTER phrase 
is your responsibility. 


The contents of identifier-10 are incremented by 1 for each character examined in 
identifier-1. When execution of an UNSTRING statement with a POINTER phrase is 
completed, identifier-10 contains a value equal to its initial value plus the number of 
characters examined in identifier-1. 


TALLYING 

Identifier-11 is a counter that records the number of data items acted on during the 
execution of an UNSTRING statement. When the execution of an UNSTRING . 
statement with a TALLYING phrase is completed, identifier-11 contains a value equal to 
its initial value plus the number of data receiving items acted upon. 


Identifier-11 must be described as an elementary-numeric-integer data item. 


The initialization of the contents of the data items associated with the TALLYING 
phrase is your responsibility. 
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ON OVERFLOW 
Either of the following situations causes an overflow condition: 


e AnUNSTRING statement is initiated, and the value in identifier-10 is less than 1 or 
greater than the size of identifier-1. 


e During execution of an UNSTRING statement, all data receiving areas have been 
acted upon and identifier-1 contains characters that have not been examined. 


When an overflow condition exists, the unstring operation ends. If an ON OVERFLOW 
phrase is specified, the imperative-statement included in the ON OVERFLOW phrase is 
executed. If the ON OVERFLOW ai is not specified, control is transferred to the 
next executable statement. 


The imperative-statement can be the NEXT SENTENCE phrase. 


Rules for Data Transfer 


-When the UNSTRING statement is initiated, the current receiving area is identifier-4. 
Data is transferred from identifier-1 to identifier-4 according to the following rules: 


e Ifthe POINTER phrase is specified, the string of characters referenced by 
identifier-1 is examined beginning with the relative character position indicated by 
the value of identifier-10. If the POINTER phrase is not specified, the string of 
characters is examined beginning with the leftmost character position. 


e Ifthe DELIMITED BY phrase is specified, the examination proceeds from left to 
right until a delimiter specified either by literal-1 or by identifier-2 is encountered. 
If the DELIMITED BY phrase is not specified, the number of characters examined 
equals the size of the current receiving area. However, if the sign of the receiving 
item is defined as occupying a separate character position, the number of characters 
examined is one less than the size of the current receiving area. 


If the end of identifier-1 is encountered before the delimiting condition is met, the 
examination terminates with the last character examined. 


e The characters thus examined, except any delimiting characters, are treated as 
elementary alphanumeric data items and are moved into the current receiving area 
according to the rules for the MOVE statement. 


e Ifthe DELIMITER IN phrase is specified, the delimiting characters are treated as 
elementary alphanumeric data items and are moved into identifier-5 according to the 
rules for the MOVE statement. If the delimiting condition is the end of identifier-1, 
then identifier-5 is space-filled. 


e Ifthe COUNT IN phrase is specified, a value equal to the number of characters thus 
examined, except any delimiting characters, is moved into identifier-6 according to 
the rules for a MOVE statement with elementary items. 
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e Ifthe DELIMITED BY phrase is specified, the string of characters is further 
examined beginning with the first character to the right of the delimiter. If the 
DELIMITED BY phrase is not specified, the string of characters is further examined 
beginning with the character to the right of the last character transferred. 


e After data is transferred to identifier-4, the current receiving area is identifier-7. 
The action described in the preceding paragraphs is repeated until the characters in 
identifier-1 are depleted or until no receiving areas remain. 


Format 2 (Unisys Extension) 


UNSTRING identifier-1 INTO identifier-4 FOR eam 
| integer-1 


, identifier-7 FOR eae | 
integer-2 


[, WITH POINTER identifier-10] [, TALLYING IN identifier-11| 


[; ON OVERFLOW imperative-statement | 


Explanation of Format 2 


All references to identifier- 4, identifier-12, and integer-1 apply saually to identifier-7, 
identifier-13, and integer-2, respectively. 


identifier-1 


Identifier-1 represents the sending area and must be described as an alphanumeric data 
item. 


identifier-4 


Identifier-4 represents the data receiving area and must be described as USAGE IS 
DISPLAY. i 


Identifier-4 can be described as alphabetic (except that the symbol B cannot be used in 
the PICTURE character string), alphanumeric, or numeric (except that the symbol P 
cannot be used in the PICTURE character string). 


The imperative-statement can be the NEXT SENTENCE phrase. _ | 
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FOR 


Integer-1 or identifier-12 specifies the number of characters in identifier-1 that are 
moved to identifier-4. If the number of characters remaining in identifier-1 is less than 
the number of characters specified by integer-1 or referenced by identifier-12, then the 
short field is transferred. Any characters examined, except delimiting characters, are 
treated as elementary alphanumeric data items and are moved into the current receiving 
area according to the rules for the MOVE statement. 


Identifier-12 must be described as an elementary-numeric-integer data item (except that 
the symbol P cannot be used in the PICTURE character string). 


POINTER 


When the UNSTRING statement is initiated, the current receiving area is identifier-4. 
Data is transferred from identifier-1 to identifier-4 according to the following rules: 


e Ifthe POINTER phrase is specified, the string of characters referenced by 
identifier-1 is examined beginning with the relative character position indicated by 
the value of identifier-10. If the POINTER phrase is not specified, the string of 
characters is examined beginning with the leftmost character position. 


e Thecharacters thus examined, except any delimiting characters, are treated as 
elementary alphanumeric data items and are moved into the current receiving area 
according to the rules for the MOVE statement. 


- Identifier-10 must be described as an elementary-numeric-integer data item. 


The initialization of the contents of the data items associated with the POINTER phrase 
is your responsibility. . 


The contents of identifier-10 are incremented by one for each character examined in 
identifier-1. When execution of an UNSTRING statement with a POINTER phrase is 
completed, identifier-10 contains a value equal to the initial value plus the number of 
characters examined in identifier-1. . 


TALLYING 

Identifier-11 is a counter that records the number of data items acted on during the 
execution of an UNSTRING statement. When the execution of an UNSTRING 
statement with a TALLYING phrase is completed, identifier-11 contains a value equal to 
its initial value plus the number of data receiving items acted upon. 


Identifier-11 must be described as an elementary-numeric-integer data item. 


The initialization of the contents of the data items associated with the TALLYING 
phrase is your responsibility. 
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ON OVERFLOW 
Each of the following situations causes an overflow condition: 
e An UNSTRING statement is initiated, and the value in identifier-10 is less than 1 or 


greater than the size of identifier-1. 


e During execution of an UN STRING statement, all data receiving areas have been 
acted upon and identifier-1 contains characters that have not been examined. 


e An UNSTRING statement is initiated, and the value in identifier-12 is less than 1 or 
greater than the size of identifier-1. (This is a Unisys extension.) 


e During execution of an UNSTRING statement, all data receiving areas have been 
acted upon and the number of characters acted upon is less than the value of 
identifier-12 or integer-1. (This is a Unisys extension.) 

When an overflow condition exists, the unstring operation ends. If an ON OVERFLOW 

phrase is specified, the imperative-statement included in the ON OVERFLOW phrase is 


executed. If the ON OVERFLOW phrase is not specified, control is transferred to the 
next executable statement. 


The imperative-statement can be the NEXT SENTENCE phrase. 


See Also 


For information about the rules of move operations, refer to “MOVE” earlier in this 
‘section. 


Examples of Format 1 
The following five examples illustrate Format 1 of the UNSTRING statement. 


Example 9-29 causes the contents of identifier-1 to be moved to identifier-4. 


UNSTRING identifier-1 INTO identifier-4. 


Variable Before After 
identifier-1 123ABC 123ABC 
identifier-4 3456789 ‘ 123ABC 


Example 9-29. Coding a Simple UNSTRING Statement 


9-146 8600 0296-000 


PROCEDURE DIVISION Statements 


Example 9-30 causes the first three characters of identifier-1 to be moved to identifier-4. 


The delimiter G ends the unstring operation. 


UNSTRING identifier-1 DELIMITED BY literal-1 INTO identifier-4. 


Variable 
literal-1 
identifier-1 
identifier-4 


After 
G 
STAGE 
STA 


Example 9-30. Coding an UNSTRING Statement Using the DELIMITED BY Option 


Example 9-31 causes the characters before the delimiter S to be moved to identifier-4. 
Identifier-7 becomes the receiving field, and the remaining characters are moved to this 


field. 


UNSTRING identifier-1 DELIMITED BY ALL literal-1 INTO identifier-4, 


identifier-7. 


Variable 
identifier-1 
literal-1 
identifier-4 
identifier-7 


After 
MISSIN 
S 

MI 


IN 


Example 9-31. Coding an UNSTRING Statement is the DELIMITED BY ALL 


At the end of the unstring operation in Example 9-32, the pointer points one character 
beyond the last character processed. Therefore, the pointer, which is identifier-10, 
equals 9 because it points to the ninth character in the string. 


UNSTRING identifier-1 INTO identifier-4 WITH POINTER identifier-19. 


Variable 
identifier-1 
identifier-4 
identifier-10 


After 
BASEBALL 
BALL 

9 


Example 9-32. Coding an UNSTRING Statement Using the WITH POINTER Option 
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9-148 


In Example 9~33, the sending string, ZSITXBYXRUN, cannot be entirely processed. 


The unstring operation ends before the remaining characters R, U, and N are 


encountered. This action causes an overflow condition. 


The TALLYING IN phrase starts a count of the number of receiving strings filled. 


UNSTRING identifier-1 DELIMITED BY literal-1 INTO identifier-4, 
DELIMITER IN identifier-5, COUNT IN identifier-6, identifier-7, 
DELIMITER.IN identifier-8, COUNT IN identifier-9 WITH POINTER 


identifier-19 TALLYING IN identifier-11l. 


Variable Before 
literal-1 . X 
identifier-1 . ZSITXBYXRUN 
identifier-4 ABCDEF 
identifier-5 

identifier-6 

identifier-7 GHIJKL 
identifier-8 

identifier-9 

identifier-10 2 
identifier-11 


After 

X 
ZSITXBYXRUN 
SIT 

X 

3 

BY 


Example 9-33. Coding an UNSTRING Statement Using Many Options 


Examples of Format 2 


The following examples illustrate Format 2 of the UNSTRING statement. 


In Example 9-34, use of the FOR phrase enables a specific number of consecutive 
characters.in a sending string to be moved to a receiving string. 


UNSTRING identifier-1 INTO identifier-4 FOR identifier-12, 


identifier-7 FOR identifier-13. 


Variable Before 
identifier-1 XTOXBEXOFXDO 
identifier-4 SUXYZ 
identifier-12 cf 

identifier-7 CDEGJKLM 
identifier-13 7 


’ After 


XTOXBEXOFXDO 
XTO 

3 

XBEXOFX 

7 


Example 9-34. Coding an UNSTRING Statement Using the FOR Option 
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In Example 9-35, use of the FOR phrase enables a specific number of consecutive 
characters in a sending string to be moved to a receiving string. The string of characters 
examined begins at position 2, as indicated by the POINTER phrase. 


Variable Before After 
identifier-1 WXYZABCD _ WXYZABCD 
identifier-12 5 5 
identifier-10 2 7 
identifier-4 CARTON ; XYZAB 


UNSTRING identifier-1 INTO identifier-4 FOR identifier-12 with POINTER 
identifier-10. 


Example 9-35. Coding an UNSTRING Statement Using FOR, WITH POINTER Options 


Example 9-36 is a sample program that uses the preceding example fragments from both 
Format 1 and 2. 


QH2000 
BB4908 
Q26200 
QBBBQB 
219080 
912008 
2149908 
216228 
918220 
220800 
922008 
924900 
226008 
Q28000 
930000 
932800 
934900 
936200 
938000 
BABGB 
B42900 
B44900 
B46920 

— BA8LOB 
B52200 
D529 
954900 
256902 
958000 
B69B20 
262928 
264900 
266000 
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IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


G1 
81 
O1 
G1 
61 
G1 
77 
77 
77 
77 
77 
77 


SOURCE6 PIC X(6). 
SOURCES PIC X(5). 
SOURCES PIC X(8). 
SOURCE11 PIC X(11). 
DEST PIC X(8). 
OTHERDEST PIC X(8). 
P PIC $9(11) BINARY. 
T PIC $9(11) BINARY. 
D PIC X. 

D2 PIC X. 

C PIC 9. 

C2 PIC 9. 


PROCEDURE DIVISION. 
LBL. 


MOVE "123ABC" TO SOURCE6. 

MOVE "3456789" TO DEST. 

DISPLAY "1. “ SOURCE6 " " DEST. 
UNSTRING SOURCE6 INTO DEST. 
DISPLAY "1. " SOURCE6 "“ " DEST. 


MOVE "STAGE" TO SOURCES. 

MOVE "CLUMP" TO DEST. 

DISPLAY "2. " SOURCES " " DEST. 

UNSTRING SOURCE5 DELIMITED BY "G" INTO DEST. 
DISPLAY "2. " SOURCES " " DEST. 


MOVE "MISSIN" TO SOURCE6. 


MOVE "WWXXYYZZ" TO DEST. 
MOVE "ABC123" TO OTHERDEST. 


Example 9-36. Sample Program Using Format 1 and 2 Examples 
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PROCEDURE DIVISION Statements 


_ 9-150 


G68800 
070889 
072008 
074808 
876808 
878800 
Q800GO 
082000 
Q84G08 
G860808 
O88000 
B9LBBO 
B92080 
B94900 
G96G28 
B9I8HBO 
190020 
192800 


184800 


1286880 
1098280 
119998 
112900 
114990 
116900 
118990 
129998 
122900 
124980 
126980 
128209 
139900 
132000 
134900 
136908 
138999 
149999 
142999 
144908 
146999 
148909 
150000 
152000 
154900 
156009 


DISPLAY "3. " SOURCE6 " " DEST " " OTHERDEST. — 
UNSTRING SOURCE6 DELIMITED BY ALL "“S" INTO DEST, OTHERDEST. 
DISPLAY "3. " SOURCE6 " " DEST " " OTHERDEST. 


MOVE "BASEBALL" TO SOURCES. 

MOVE "FOOTBALL" TO DEST. 

MOVE 5 TO P. 

DISPLAY "4. " SOURCES " " DEST " " P. 
UNSTRING SOURCES INTO DEST WITH POINTER P. 
DISPLAY "4. " SOURCE8 " " DEST " " P, 


MOVE "ZSITXBYXRUN" TO SOURCE11 

MOVE "ABCDEF" TO DEST. 

MOVE "GHIJKL" TO OTHERDEST. 

MOVE 2 TO P. . 

MOVE @ TO T. 

MOVE "" TO D, D2. 

MOVE @ TO C, C2. 

DISPLAY “55 .*  SOURCEL IT "DEST "Boe? 
DISPLAY “5. * OTHERDEST  * D20" <P .C2 (© ™ 


C. 
P ee L T. 


UNSTRING SOURCE11 DELIMITED BY "X" INTO DEST 


DELIMITER IN D, COUNT INC, 

OTHERDEST, DELIMITER IN D2, COUNT IN 

WITH POINTER P TALLYING IN T. 
DISPLAY "5. " SOURCE11 " "DEST ""D" " 
DESPEAY -"53.,° OTHERDEST, “D2. C2048" 


MOVE "XTOXBEXOFXDO" TO SOURCE11. 
MOVE "SUXYZ" TO DEST. 


MOVE 3 TOC. 

MOVE "CDEGJKLM" TO OTHERDEST. 

MOVE 7 TO C2. 

DISPLAY "6. " SOURCE11 """ DEST" "Cc" " 


C2 


C. 
) no Ae 


OTHERDEST " " C2. 


UNSTRING SOURCE11 INTO DEST FOR C, OTHERDEST FOR C2. 


DISPEAY: “6: “SSOURCELI. DEST @ Cc" ® 


MOVE "WXYZABCD" TO SOURCE11. 
MOVE "CARTON" TO DEST. 

MOVE 5 TO C. 

MOVE 2 TO P. 


OTHERDEST " " C2. 


DISPLAY "7. " SOURCE11 """C " "PP " " DEST. 
UNSTRING SOURCE11 INTO DEST FOR C WITH POINTER P. 
DISPLAY "7. " SOURCE11 ""C " " P" " DEST. 


STOP RUN. 


Example 9-36. Sample Program Using Format 1 and 2 Examples (cont.) 
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PROCEDURE DIVISION Statements 


Example 9-37 shows the output from the previous program. 


RUN UNSTRING/TEST 


#RUNNI 
#5199 
#5109 
#5189 
#5169 
#5109 
#5109 
#5109 
#5199 
#5109 
#5109 
#5169 
#5109 
#5109 
#5109 
#5109 
#5109 


USE 


NG 5199 


DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 
DISPLAY: 


1. 
ae 
25 
2. 
oe 


7. 
Example 9-37. Display from UNSTRING Program 


SNS DD OM H MN PP LP W 
ee @ @ @ > ee $e © 


123ABC 3456789 . 
123ABC 123ABC . 
STAGE CLUMP. 


STAGE STA : 
MISSIN WWXXYYZZ ABC123 
MISSIN MI IN 


BASEBALL FOOTBALL +80000922005. 
BASEBALL BALL +0QOOLVOOHWB09. 
ZSITXBYXRUN ABCDEF QB. 


« GHIJKL D +QOQPOOOGLKH2 +OGPOPBVOGWO. 


ZSITXBYXRUN SIT X 3. 

BY X 2 +QBOOPLOGGH9 +OGGVGHHOGH2. 
XTOXBEXOFXD SUXYZ 3 CDEGJKLM 7. 
XTOXBEXOFXD XTO 3 XBEXOFX 7. 


WXYZABCD 5 +QG20BGPBVHGH2 CARTON 
WXYZABCD 5 +Q0000OGL00B7 XYZAB 


A USE statement, when present, must immediately follow a section header in the 
DECLARATIVES SECTION and must be followed by a period. The remainder of the 
sections consist of any number of procedural paragraphs that define the procedures to be 


used. 


‘The USE statement itself is never executed; it merely defines conditions that call for the 
execution of USE procedures. 


The USE statement has the following four formats: 


Format 


1 


2 
3 
4 
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Explanation 


_ Specifies supplemental procedures for |-O error and tape-label handling 


Specifies procedures for tape-file-label handling 


Specifies procedures to be employed in a parallel processing environment 


Specifies interrupt procedures 


9-151 


PROCEDURE DIVISION Statements 


OUTPUT 
The exception handling procedures are executed for any file opened in output mode, 


or in the process of being opened in output mode, except if the file is referenced by 
file-name in another USE statement specifying the same condition. 


1/0 
The exception handling procedures are executed for any file opened in I/O mode, or in 


the process of being opened in I/O mode, except if the file is referenced by file-name in 
another USE statement specifying the same condition. 


EXTEND 
The EXTEND phrase applies only to sequentially organized files. The exception 
handling procedures are executed for any file opened in extended mode, or in the process 


of being opened in extended mode, except if the file is referenced by file-name in another 
USE statement specifying the same condition. 


Format 2 


AFTER aaa a | 
USE cee | STANDARD ENDING | REEL LABEL PROCEDURE ON 


INPUT 5 
june 


file-name-1 [, fileename-2]... 


Explanation of Format 2 


Format 2 enables you to define up to nine tape labels (header and trailer records) that 
are each 80 characters long. The first four characters of each label are used by the 
system for maintaining the label identity. For example, header labels contain UHLn, and 
trailer labels contain UTLn, where n can be a number from 1 through 9. You can use the: 
remaining 76 characters for storing any desired information. 


You can define the labels in the WORKING-STORAGE SECTION or in the FILE 
SECTION in the respective file-description (FD) entry for the file. If you use multiple 


labels, you must define all labels in the same area, either in the FD entry, or in the 
WORKING-STORAGE SECTION. 


AFTER or BEFORE 


The AFTER and BEFORE phrases determine when the I/O subsystem executes the. 
designated procedures. 
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PROCEDURE DIVISION Statements 


- The INPUT and OUTPUT phrases can each be specified only once for any USE AFTER 
LABEL or USE BEFORE LABEL statement. The procedures are not executed for any 
file whose file-description (FD) entry specifies LABEL RECORDS ARE OMITTED. 


When the INPUT phrase or OUTPUT phrase is used, references to label data items 
must be qualified. 


file-name 


When the USE BEFORE LABEL file-name-1 clause is specified, the designated 
procedure is executed before the tape header or trailer records are read or written. 


When the USE AFTER LABEL file-name-1 clause is specified, the designated procedure 
is executed after the tape header or trailer records are read or written. 


The appearance of file-name-1 ina USE AFTER LABEL or a USE BEFORE LABEL 
statement must not cause the simultaneous request for execution of more than one 
USE AFTER LABEL or USE BEFORE LABEL procedure. That is, when file-name-1 is 
specified explicitly, no other USE AFTER LABEL or USE BEFORE LABEL statement 
can apply to file-name-1. The file-description (FD) entry for file-ename-1 must not specify 
LABEL RECORDS ARE OMITTED. 


The program must not open or close the file associated with the USE AFTER LABEL or 
USE BEFORE LABEL statement within that procedure. 


Those files referenced by file-name-1 in USE AFTER LABEL or USE BEFORE LABEL 
statements are not included in any input or output procedures. 


The same file-name can appear in a-different specific arrangement of the format. The 


appearance of a file-name in a USE statement must not cause a simultaneous request for 
execution of more than one USE procedure. 


See Also 


Further information on labels can be found in the I/O Subsystem Programming Guide. 


Format 3 (Unisys Extension) 


identifier-1 
mnemonic-name 
AS GLOBAL PROCEDURE 


SE — { 


\ AS a, 


file-name-1 file-name-2 
; USING identifier-2 [, identifier-3] ... 


. WITH orice aaa f eteaily seacaas | 7 
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Example 9-37 shows the output from the previous program. 


RUN UNSTRING/TEST 


#RUNNI 
#5109 
#5189 
#5189 
#5199 
#5109 
#5109 
#5189 
#5169 
#5109 
#5109 
#5189 
#5109 
#5109 
#5189 
#51989 
#5169 


USE 


NG 5199 

DISPLAY:1. 
DISPLAY :1. 
DISPLAY :2. 
DISPLAY :2. 
DISPLAY:3. 
DISPLAY :3. 
DISPLAY:4. 
DISPLAY :4. 
DISPLAY:5. 
DISPLAY:5.. 
DISPLAY:5. 
DISPLAY:5. 
DISPLAY :6. 
DISPLAY :6. 
DISPLAY :7. 
DISPLAY:7. 


123ABC 3456789 . 

123ABC 123ABC . 

STAGE CLUMP. 

STAGE STA . 

MISSIN WWXXYYZZ ABC123 

MISSIN MI IN - 

BASEBALL FOOTBALL +@2220000005. 
BASEBALL BALL +QOQOL0OGLLB9. 
ZSITXBYXRUN ABCDEF 8. 

GHIJKL GB +POQOLQWOLPHG2 +OGVOOOGHSOHO. 


ZSITXBYXRUN SIT X 3. 

BY X 2 +OQOLQGOWLOLI +OGOGLOGLOL2. 
XTOXBEXOFXD SUXYZ 3 CDEGJKLM 7. 
XTOXBEXOFXD XTO 3 XBEXOFX 7. 


WXYZABCD 5 +0QOLQPPGBG0H2 CARTON 
WXYZABCD 5 +Q000G000007 XYZAB 


Example 9-37. Display from UNSTRING Program 


A USE statement, when present, must immediately follow a section header in the 
_ DECLARATIVES SECTION and must be followed by a period. The remainder of the 
sections consist of any number of procedural paragraphs that define the procedures to be 


used. — 


The USE statement itself is never executed; it merely defines conditions that call for the 
execution of USE procedures. 


The USE statement has the following four formats: 


Format 


i 
2 
3 
4 
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Explanation 


_ Specifies supplemental procedures for !-O error and tape-label handling 


Specifies procedures for tape-file-label handling 


Specifies procedures to be employed in a parallel processing environment 


Specifies interrupt procedures 
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PROCEDURE DIVISION Statements 


USE AFTER STANDARD { 


9-152 


Format 1 


{file-name} ... 
INPUT 
} PROCEDURE ON < OUTPUT 
| I-O 
EXTEND 


EXCEPTION 
ERROR 


Explanation of Format 1 
The USE AFTER statement specifies procedures for I/O exception handling. 
After execution of a USE procedure, control is returned to the invoking routine. 


The status key of a file can be used to determine the nature of the exception that 
occurred. 
In a USE procedure, no reference can be made to any nondeclarative procedure. 
Conversely, in the nondeclarative portion of a program, no reference can be made to 
procedure-names that appear in the DECLARATIVES SECTION. The exception is that 
PERFORM statements in the nondeclarative portion of a program can refer to Format 1 
USE statements or to procedures associated with a Format 1 USE statement. 


ERROR and EXCEPTION 


The words ERROR and EXCEPTION are synonymous and can be used interchangeably. 


file-name 


The designated procedures are executed on recognition of any error or exception for the 
file, including an end-of-file exception when no AT END clause has been specified. 


The same file-name can appear in a different specific arrangement of the format. The 
appearance of a file-name in a USE statement must not cause a simultaneous request for 
execution of more than one USE procedure. 


The files implicitly or explicitly referenced in a USE statement need not all have the 
same organization or access. 


INPUT 
The exception handling procedures are executed for any file opened in input mode, or in 


the process of being opened in input mode, except if the file is referenced by file-name in 
another USE statement specifying the same condition. 
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OUTPUT 
The exception handling procedures are executed for any file opened in output mode, 


or in the process of being opened in output mode, except if the file is referenced by 
file-name in another USE statement specifying the same condition. 


1/0 
The exception handling procedures are executed for any file opened in I/O mode, or in 


the process of being opened in I/O mode, except if the file is referenced by file-name in 
another USE statement specifying the same condition. 


EXTEND 
The EXTEND phrase applies only to sequentially organized files. The exception 
handling procedures are executed for any file opened in extended mode, or in the process 


of being opened in extended mode, except if the file is referenced by file-name in another 
USE statement specifying the same condition. 


Format 2 


AFTER ae foe | 
USE ee 4 STANDARD ENDING | REEL LABEL PROCEDURE ON 


INPUT 
OUTPUT 


file-name-1 [, file-name-2]... 


Explanation of Format 2 


Format 2 enables you to define up to nine tape labels (header and trailer records) that 
are each 80 characters long. The first four characters of each label are used by the 
system for maintaining the label identity. For example, header labels contain UHLn, and 
trailer labels contain UTLn, where n can be a number from 1 through 9. You can use the: 
remaining 76 characters for storing any desired information. 


You can define the labels in the WORKING-STORAGE SECTION or in the FILE © 
SECTION in the respective file-description (FD) entry for the file. If you use multiple 
labels, you must define all labels in the same area, either in the FD entry, or in the 
WORKING-STORAGE SECTION. 


AFTER or BEFORE 


The AFTER and BEFORE phrases determine when the I/O subsystem executes the. 
designated procedures. 
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9-154 


After execution of a USE AFTER LABEL or a USE BEFORE LABEL statement, control 
passes to the invoking routine in the I/O subsystem. If the I-O status value does not 
indicate a critical I/O error, the I/O subsystem returns control to the next executable 
statement that follows the I/O statement whose execution caused the USE procedure to 
be invoked. 


A USE AFTER or a USE BEFORE statement must immediately follow a section header 
in the DECLARATIVES SECTION and must appear in a sentence by itself. The _ 
remainder of the section must consist of any number of procedural paragraphs that 
define the procedures to be used. 


The USE AFTER LABEL or the USE BEFORE LABEL statement is never executed 
itself; it merely defines the condition calling for the execution of the USE procedures. 


A declarative procedure must not reference any nondeclarative procedures. The 
procedure-names associated with the USE AFTER LABEL statement or the USE 
BEFORE LABEL statement can be referenced in a different DECLARATIVE 
SECTION, or in a nondeclarative procedure with only a PERFORM statement. 


BEGINNING or ENDING 


The BEGINNING phrase specifies that USE procedures are executed for header labels. 
The ENDING phrase specifies that USE procedures are executed for trailer labels. If 
the BEGINNING phrase or the ENDING phrase is not included, the USE procedure is 
executed for both header and trailer labels. 


FILE or REEL 


The REEL phrase specifies that the USE procedure is executed for reel labels. The 
FILE phrase specifies that the USE procedure is executed for file labels. If the FILE 
phrase or the REEL phrase is not included, the USE procedure is executed for both file 
and reel labels. 


INPUT or OUTPUT 


The input procedure is a label-checking procedure. When the USE BEFORE LABEL 
INPUT clause is specified, the designated procedure is executed before the tape header 
or trailer label records are read. 


When the USE AFTER LABEL INPUT clause is specified, the designated procedure is 
executed after the tape header or trailer label records are read. 


The output procedure is a label writing procedure. When the USE BEFORE LABEL 
OUTPUT clause is specified, the designated procedure is executed before the tape 
header or trailer label records are written. 


When the USE AFTER LABEL OUTPUT clause is specified, the designated procedure 
is executed after the tape header or trailer label records are written. 
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- The INPUT and OUTPUT phrases can each be specified only once for any USE AFTER 
LABEL or USE BEFORE LABEL statement. The procedures are not executed for any 
file whose file-description (FD) entry specifies LABEL RECORDS ARE OMITTED. 


When the INPUT phrase or OUTPUT phrase is used, references to label data items 
must be qualified. 


file-name 


When the USE BEFORE LABEL file-name-1 clause is specified, the designated 
procedure is executed before the tape header or trailer records are read or written. 


When the USE AFTER LABEL file-name-1 clause is specified, the designated procedure 
is executed after the tape header or trailer records are read or written. 


The appearance of file-name-1 in a USE AFTER LABEL or a USE BEFORE LABEL 
statement must not cause the simultaneous request for execution of more than one 
USE AFTER LABEL or USE BEFORE LABEL procedure. That is, when file-name-1 is 
specified explicitly, no other USE AFTER LABEL or USE BEFORE LABEL statement 
can apply to file-name-1. The file-description (FD) entry for file-name-1 must not specify 
LABEL RECORDS ARE OMITTED. 


The program must not open or close the file associated with the USE AFTER LABEL or 
USE BEFORE LABEL statement within that procedure. 


Those files referenced by file-name-1 in USE AFTER LABEL or USE BEFORE LABEL 
statements are not included in any input or output procedures. 


The same file-name can appear in a.different specific arrangement of the format. The 


appearance of a file-name in a USE statement must not cause a simultaneous request for 
execution of more than one USE procedure. 


See Also 


Further information on labels can be found in the I/O Subsystem Programming Guide. 


Format 3 (Unisys Extension) 


EXTERNAL ieee \ AS PROCEDURE 
USE mnemonic-name 
AS GLOBAL PROCEDURE 


file-name-1 file-name-2 
; USING identifier-2 [, identifier-3] ... 


. WITH oo | eased aeemes| " | 
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Explanation of Format 3 


Format 3 enables untyped procedures or subroutines to be declared global in the same 
way that they can be declared external. The GLOBAL phrase identifies a procedure that 
exists in the host program and is to be called in a bound procedure. 


There must be no paragraphs in a section with a USE EXTERNAL or USE AS GLOBAL 
PROCEDURE phrase. 


EXTERNAL 


The EXTERNAL phrase identifies a separately compiled program that is to be used 

as a task when the section is referenced. The EXTERNAL phrase can also identify 

a separately compiled program to be bound into the COBOL74 host program. The 
distinction is made by the format of the CALL statement that invokes the procedure or 
initiates the task. 


Identifier-1 must be defined in the WORKING-STORAGE SECTION in such a way 
that its value can be a program-name. If mnemonic-name is used, it must be defined in 
the SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION to represent a 
program-name. 


A program with the USE EXTERNAL PROCEDURE statement is not marked as 
library-capable. 


GLOBAL 


The GLOBAL phrase identifies a procedure in the host program that is referenced ina 
bound procedure. 


WITH 


Local-storage-names must be defined in the LOCAL-STORAGE SECTION. A 
local-storage-name must be present if the USING phrase is present. 


The files implicitly or explicitly referenced in a USE statement need not all have the 
same organization or access. 


USING 


The USING phrase is included in the USE statement if there is a USING phrase in 
the PROCEDURE DIVISION header of the referenced, separately compiled program. 
The number, type, and order of the operands in the two USING phrases must then be 
identical. 


Identifier-2 and so forth must be uniquely defined as files in the FILE SECTION or as 
01-level or 77-level items of the local-storage-name specified in the WITH phrase. These 
identifiers can describe any combination of data items, task (controlpoint) items, EVENT 
items, or lock items. 
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Format 4 (Unisys Extension) 


USE AS INTERRUPT PROCEDURE. . 


Explanation of Format 4 


The INTERRUPT PROCEDURE phrase specifies a declarative as an interrupt 
procedure. 


An interrupt procedure provides a means of interrupting a process when an EVENT 
item attached to that procedure is caused. Statements to be executed when the event is 
caused and the interrupt procedure is allowed must follow the USE statement. 


When an interrupt procedure is being executed, all other interrupts are disallowed 
during the execution. That is, an interrupt procedure cannot itself be interrupted. 


See Also 


e For more information on the mechanism for handling interrupt procedures, refer to 
“ALLOW (Unisys Extension),” “ATTACH (Unisys Extension),” “CAUSE (Unisys 
' Extension),” “DETACH (Unisys Extension),” “DISALLOW,” and “RESET (Unisys 
Extension)” earlier in this section. 


e For information on specifying an EVENT item, refer to “USAGE Clause” in 
Section 7, “DATA DIVISION.” 


WAIT (Unisys Extension) 


The WAIT statement suspends the execution of the object program for a specified time 
or until one or more conditions are TRUE. 


The WAIT statement has the following three formats: 


Format Explanation 
1 Suspends an object program for a specified number of seconds 
2 Suspends an object program until an event is caused 
3. Suspends an object program until execution of an interrupt procedure 
Format 1 


WAIT UNTIL arithmetic-expression 
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Explanation of Format 1 


When an arithmetic-expression is specified, the execution of the object program is 
suspended for the number of seconds determined by the value of the expression. 


Format 2 


WAIT [ AND RESET ] UNTIL | arithmetic-expression, | 


ODT-INPUT-PRESENT 
f event-identifier-1 . ..{ GIVING identifier-1 ] 
READ-OK [ ON ] file-name 1 


Explanation of Format 2 


Format 2 causes a suspension for the number of seconds specified by the 
arithmetic-expression (if present) or until one of the event-identifiers has been caused. 


If any event in the list is TRUE, the WAIT statement ends and control passes to the next 
executable statement. — 


If, in the initial scan of the events, no event is found to be TRUE, program execution is 


suspended until any event in the list becomes TRUE. When an event becomes TRUE, 
the WAIT statement ends and control passes and the next executable statement. 


AND RESET 
If the AND RESET phrase is specified, the event-identifier that causes the 
WAIT statement to end is reset. If the number of seconds specified by the . 


arithmetic-expression has elapsed before an event is caused, the AND RESET phrase 
has no effect. 


arithmetic-expression 


When an arithmetic-expression is specified, the execution of the object program is 
suspended for the number of seconds determined by the value of the expression. 


‘No more than one arithmetic-expression can be specified, and if specified, it must be the 
first item in the list. 
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ODT-INPUT-PRESENT 

The ODT-INPUT-PRESENT clause is a special event-identifier. This event is caused 
whenever input is sent to the process by way of the AX (accept) system command. Using 
an ODT device to execute an ACCEPT statement causes the event to be reset. The 
event can also be reset with the AND RESET syntax. 

No more than one ODT-INPUT-PRESENT clause can be specified. 


Note: No more than one ACCEPT message can be queued. This event 
corresponds to the system attribute ACCEPTEVENT. 


event-identifiers 


Event-identifiers must be either data items with event usage or file or task attributes of 
type EVENT. 


The EXCEPTIONEVENT attribute of a task-identifier is a special case event-identifier. 
The behavior of the WAIT statement is the same as that for other event-identifiers. 


- READ-OK 
When the READ-OK option is specified, the program is suspended until there is at least 


one record to be read in file-name-1. For files that are not open, the event is always 
FALSE. This event can only be used with port files and remote files. 


GIVING 

When the GIVING option is specified, the data item referenced by identifier-1 is set to 
the position in the list of the data item that ended the WAIT statement. For example, if 
the second event in the list of events is TRUE, the data item referenced by identifier-1 is 
set to the value 2. 


Identifier-1 must be described as an elementary-numeric-integer data item without the 
symbol P in its PICTURE character string. 


See Also . 


For information about the event-identifier condition, refer to “Conditional DEETeenOne: 
in Section 8, “PROCEDURE DIVISION Concepts.” 
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Format 3 


WAIT UNTIL INTERRUPT 


Explanation of Format 3 


The INTERRUPT phrase causes execution of this task to be suspended until at least 
one of its interrupt procedures has been executed. After execution of the interrupt 
procedure, the task is again suspended. Thus, the WAIT INTERRUPT construct 
provides a mechanism for an interrupt-driven program. The program runs indefinitely 
unless one or more of the interrupt procedures contain a STOP RUN statement. 


WRITE 


9-160 


The WRITE statement releases a logical record to a file. Also, it specifies the vertical 
position of lines on a logical page. 


The file must be open in the OUTPUT, I-O, or EXTEND mode for the write operation to 
be successful. 


The WRITE statement does not affect the current-record pointer. 


A write operation updates the value of the FILE STATUS data item associated with the 
file. . 


The WRITE statement has the following five formats: 


Format Explanation 
1 Writes records to a sequential file, and positions lines vertically on a logical page. 
2 Records to sequential, relative, and indexed files. This format can be used with 
port files. 
3 Creates Kanji records, positions lines vertically on a logical page, and writes the 


records to a sequential file. This format is for use with remote or printer files. 
4 _ Creates Kanji records and writes them to sequential, relative, or indexed files. 


Used with form libraries. Refer to Volume 2 for information on the WRITE FORM 
statement. 
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Format 1: Sequential I/O and Vertical Positioning of Lines 


Format 1 is used for files of sequential organization that are not on mass-storage devices. 


Format 1 
WRITE record-name | FROM identifier-1 | 
integer LINES 


mnemonic-name 
PAGE 


{ identifier-2 \ ane | 


END-OF-PAGE 
EOP 


\ imperative-statement | 


Explanation of Format 1 


record-name 


The record-name is the name of a logical record in the FILE SECTION of the DATA 
DIVISION and can be qualified. 


FROM 

The FROM option makes the WRITE statement operate like a MOVE statement 
followed by a WRITE statement. The move takes place according to the rules of the 
MOVE statement without the CORRESPONDING option. _ 


Record-name and identifier-1 must not reference the same storage area. 


BEFORE 


If the BEFORE phrase is used, the line is presented before the representation of the 
printed page is advanced according to rules described for the ADVANCING phrase. 


AFTER 


If the AFTER phrase is used, the line is presented after the representation of the 
printed page is advanced according to rules described for the ADVANCING phrase. 
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ADVANCING 


The ADVANCING phrase controls the vertical positioning of each line on a 
representation of a printed page. If the ADVANCING phrase is not used, automatic 
advancing is provided as if AFTER ADVANCING 1 LINE were specified. If the 
ADVANCING phrase is used, advancing is provided as follows: 


If identifier-2 is specified, the representation of the printed page is advanced a 
number of lines equal to the value of identifier-2. The variable identifier-2 must be 
the name of an elementary integer data item and can be equal.to 0 (zero). 


If an integer is specified, the representation of the printed page is advanced a 
number of lines equal to the value of integer. The integer can be 0 (zero). 


If a mnemonic-name is specified, the representation of the printed page is advanced 
to the line number corresponding to the channel number. The mnemonic-name 
must be associated with a channel number. The mnemonic-name is defined in the 
SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION. 


The ADVANCING mnemonic-name phrase cannot be specified when writing a 
record to a file that has a file-description (FD) entry that contains the LINAGE 
clause. 


If the PAGE option is specified, the record is presented on the logical page either 
before or after the device is repositioned to the next logical page. If the record to 
be written is associated with a file that has a LINAGE clause in its file-description 
(FD) entry, the device is repositioned to the first line that can be written on the 
next logical page, as specified in the LINAGE clause. If the record to be written is 
associated with a file that does not have a LINAGE clause in its file-description (FD) 
entry, the device is repositioned to channel 1 or, when appropriate for the hardware 
device, to the next logical page. 


If the PAGE option has no meaning in conjunction with a specific device, then the 
page is adjusted as if BEFORE ADVANCING ONE LINE or AFTER ADVANCING 1 
LINE (depending on the phrase used) were specified. 


END-OF-PAGE (EOP) 


The END-OF-PAGE phrase enables you to control the vertical positioning of each line on 
a representation of a printed page. 


If the END-OF-PAGE phrase is specified, the LINAGE clause must be specified in the 
file-description (FD) entry for the associated file. 


If the logical end of the representation of the printed page is reached during execution 
of a WRITE statement with the END-OF-PAGE phrase, the imperative-statemént 
specified in the END-OF-PAGE phrase is executed. The logical end is specified in the 
LINAGE clause associated with record-name. 


An End-Of-Page condition is reached whenever execution of a given WRITE statement 
with the END-OF-PAGE phrase causes printing or spacing within the footing area of a 
page body. This condition occurs when execution of such a WRITE statement causes 
the LINAGE-COUNTER, a special register, to equal or exceed the value specified by 


integer-6 or by the data item referenced by data-name-7 of the LINAGE clause. If 
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the End-Of-Page condition occurs, the WRITE statement is executed and then the 
imperative-statement in the END-OF-PAGE phrase is executed. 


An automatic Page-Overflow condition is reached whenever the execution of a WRITE 
statement (with or without an END-OF-PAGE phrase) cannot be fully accommodated 
within the current page body. This condition occurs when a WRITE statement 

causes the LINAGE-COUNTER register to exceed the value specified by integer-5 or 
data-name-6 of the LINAGE clause. If the Page-Overflow condition occurs, the record is 
presented on the logical page before or after (depending on the phrase used) the device 
is repositioned to the first line that can be written on the next logical page (as specified 
in the LINAGE clause). The imperative-statement in the END-OF-PAGE clause, if 
specified, is executed after the record is written and the device has been repositioned. 


If the FOOTING phrase of the LINAGE clause is not specified, no End-Of-Page (EOP) 
condition distinct from the Page-Overflow condition is detected. In this case, the 
End-Of-Page (EOP) condition and Page-Overflow condition occur simultaneously. 


If the FOOTING phrase of the LINAGKE clause is specified, but execution of a given 
WRITE statement causes the LINAGE-COUNTER register to simultaneously exceed 
the value of both of the following items, then the operation proceeds as if mteeer -6 or 
data-name-7 had not been specified: 


e  Integer-6 or the data item referenced by data-name-7 


e Integer-5 or the data item referenced by data-name-6 
The words END-OF-PAGE and EOP are equivalent. 


The imperative-statement can be the NEXT SENTENCE phrase. 


Format 2: Sequential, Relative, and Indexed 1/O 


Format 2 is used for mass-storage files of any organization. Format 2 must be used for 
port files. (Port files are a Unisys extension.) 


Format 2 


NO WAIT 
WITH {uRcea 
NO WAIT URGENT 
SYNCHRONIZED 


WRITE record-name 


[ FROM identifier-1 | 


| [ ; INVALID KEY imperative-statement | 
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Explanation of Format 2 


record-name | 


The record-name is the name of a ere record in the FILE SECTION of the DATA 
DIVISION and can be qualified. 


WITH 


The WITH phrase can be specified only for port files. The NO WAIT and URGENT 
phrases can be included only once each, either individually or together. (These phrases 
are Unisys extensions.) 


The WITH URGENT phrase is meaningful only when the Transmission Control 
Protocol/Internet Protocol (TCP/IP) is being used. The WITH URGENT phrase sets the 
urgent indicator associated with the data. For more information on TCP/IP refer to the 
A Series Distributed Systems Services (DSS) Operations Guide. 


SYNCHRONIZED 


Synchronization of all output records can be designated with the SYNCHRONIZE 

file attribute. Synchronization means that output must be written to the physical 

file before the program initiating the output can resume execution, thereby ensuring 
synchronization between logical and physical files. The SYNCHRONIZED clause 
enables you to override the synchronization specified by the file attribute for a specific 
output record. A periodic synchronous WRITE statement that follows one or more _ 
asynchronous WRITE statements can be used as a checkpoint to ensure that all 
outstanding records are written to the file before the program continues execution. 
Synchronization is available for use by tape files and disk files with sequential 
organization only, and is not available for use by port files. 


FROM 

The results of the execution of the WRITE statement with the FROM phrase is 
equivalent to the execution of the statement MOVE identifier-1 TO record-name 
according to the rules specified for the MOVE statement, followed by the same WRITE 
statement without the FROM phrase. 


Record-name and identifier-1 must not reference the same storage area. 


INVALID KEY 


When the Invalid Key condition occurs, any FILE STATUS data item of the file is set to 
a value indicating the cause of the condition. 


The imperative-statement can be the NEXT SENTENCE phrase. 
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See Also 


For information about the status of I/O operations, refer to “I/O Status” in Section 5, 
“ENVIRONMENT DIVISION.” 


Sequential 1/0 


For a mass-storage file with sequential access mode, the execution of a Format 2 WRITE 
statement releases the record area to the next logical record in the file. 


If the ACTUAL KEY phrase is specified for a mass-storage file with sequential access 
mode, the successful execution of a Format 2 WRITE statement updates the contents of 
the ACTUAL KEY data item to the ordinal number of the logical record written. 


For a mass-storage file with random access mode, the execution of a Format 2 WRITE 
statement releases the record area to the logical record of the file specified by the 
contents of the ACTUAL KEY data item. 


Additionally, for a mass-storage file with random access mode, an Invalid Key condition 
exists when the value of the ACTUAL KEY data item is less than one or greater than 
the ordinal number of the last logical record allowed for the file, if the maximum logical 
size of the file is specified. 


For a mass-storage file with sequential access mode, the Invalid Key condition exists 
when a maximum logical size has been specified for the file and no more logical records 
can be written. 


Relative I/O 


When a file is opened in the OUTPUT mode, records can be placed in the file by one of 
the following methods: . 


e Ifthe access mode is sequential, the WRITE statement causes a record to be 
released to the I/O subsystem. The first record has an ordinal record number of 
1, and subsequent records released have ordinal record numbers of 2, 3, 4, and so 
on. If the relative key data item has been specified in the file-control entry for the 
associated file, the ordinal record number of the record just released is placed in 
the relative key data item by the I/O subsystem during execution of the WRITE 
statement. 


e Ifthe access mode is random or dynamic, then prior to the execution of the WRITE 
statement, the value of the relative key data item must be initialized in the program 
with the relative record number to be associated with the record in the record area. 
Execution of the WRITE statement releases that record in the I/O subsystem. 


When a file is opened in the I-O mode and the access mode is random or dynamic, 
records are inserted in the associated file. The value of the RELATIVE KEY data item 

‘ must be initialized by the program with the relative record number associated with the 
record in the record area. Execution of a WRITE statement then causes the contents of 
the record area to be released to the I/O subsystem. 
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The Invalid Key condition occurs under the following circumstances: 


e The access mode is random or dynamic, and the RELATIVE KEY data item specifies _ 
a record already present in the file. 


e Anattempt is made to write beyond the logical boundaries of the file. 


Indexed I/O 


‘Execution of the WRITE statement causes the contents of the record area to be 


released. The I/O subsystem uses the contents of the record keys so that subsequent 
access of the record key can be made based on any of the specified record keys. 


The value of the prime record key must be unique within the records in the file. 


The data item specified as the prime record key must be set by the program to the 
desired value prior to execution of the WRITE statement. 


If sequential access mode is specified for the file, records must be released to the I/O 
subsystem in ascending order of prime record key values. 


If random or dynamic access mode is specified, records can be released to the I/O 
subsystem in any order. . 


When the ALTERNATE RECORD KEY clause is specified in the file-control entry 

for an indexed file, the value of the alternate record key can be nonunique only if the 
DUPLICATES phrase is specified for that data item. In this case, the I/O subsystem 
provides storage of records so that when records are accessed sequentially, the order of 
retrieval of those records is the order in which they are released to the I/O subsystem. 


The Invalid Key condition occurs under the following circumstances: 


e Sequential access mode is specified for a file opened in the OUTPUT mode, and the 
value of the prime record key is not greater than the value of the prime record key of 
the previous record. 


e The file is opened in the OUTPUT or I-O mode, and the value of the prime record 
key equals the value of a prime record key of a record already present in the file. 


e The file is opened in the OUTPUT or I-O mode, and the value of an alternate record 
key for which duplicates are not allowed equals the corresponding data item of a 
record already present in the file. 


Port Files (Unisys Extension) 


9-166 


A WRITE statement causes the program to wait until a buffer is available to store the 
record. For port files, you can prevent the possibility of this suspension by using the 
WITH NO WAIT phrase. A status key value of 95 indicates that no buffer was available 
for the logical record. | 


If you declare an ACTUAL KEY clause for a port file, you are responsible for updating 
the actual key with an appropriate value. A WRITE statement causes the actual key 
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value to be passed to the I/O subsystem to indicate the desired subfile destination. If 
the actual key value is 0 (zero), the program performs a broadcast write operation. A 
broadcast write operation sends data to all opened subfiles of the port file. 


If no ACTUAL KEY clause is declared for the file, the file must contain a single subfile 
that is written. 


Formats 3 and 4: Kanji Delimiters 
The WRITE DELIMITED statement formats a record into a scratch array by inserting 
start-of-double-octet (SDO) and end-of-double-octet (EDO) delimiters before and after 
each eligible Kanji item in the specified format record. The resulting scratch array is 
then transferred to the I/O subsystem. 


The hexadecimal values for the delimiter characters are as follows: 


Delimiter Value 

SDO 2B 

EDO 2C 
Format 3 


WRITE DELIMITED record-name [ FROM identifier-1 | 


[ USING identifier-2 ] 


identifier-3 LINE 
{ integer } fee | 
{ mnemonic-name ). 
PAGE } 


ae 


AFTER \ ADVANCING 


| AT ‘eon 


EOP } imperative-statement | 


Format 4 


WRITE DELIMITED record-name [ FROM identifier-1 | [ USING identifier-2 | 


[ ; INVALID KEY imperative-statement | 
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Explanation of Formats 3 and 4 


The records named ina WRITE DELIMITED statement are maintained according to the 
rules for a WRITE statement without the DELIMITED phrase. 


The WRITE DELIMITED statement can involve the physical areas that match any of 
the four following descriptions: 


e The target record is the record described in the file description (FD) whose name 
follows DELIMITED in the syntax. 

e The source record is the record in the FROM phrase. 

e The format record is the record in the USING phrase. 

e The output record is the actual physical array used to contain the formatted result. 

If neither the USING phrase nor the FROM phrase is specified, the target record is used 

as both the source record and the format record. If only the FROM phrase is used, the 

source record is first moved to the target record, and then the source record is used as 


the format record. If only the USING phrase is present, the target record is used as the 
source record, and the final formatting is performed using the format record. 


The compiler uses s the descriptions of the format record to transfer the data into the 
output record. 


Eligible Kanji items are those elementary Kanji items that neither specify nor are 
subordinate to an item containing a REDEFINES or RENAMES clause. 


Record-name and identifier-1 must not reference the same storage area. 


The record-name is the name of a logical record in the FILE SECTION of the DATA 
DIVISION and can be qualified. 


When a mnemonic-name is specified, it must be associated with a channel number. The 
mnemonic-name is defined in the SPECLIAL-NAMES paragrap of the ENVIRONMENT 
DIVISION. 


The integer and the value of the data item are referenced by identifier-2 and identifier-3, 
respectively. 


Format 3 can be used only for remote or printer files. 
Format 4 can be used only for remote files. 


When the FROM phrase is used, identifier-1 and identifier-2 must not be the name of a 
RENAMES clause. 
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The ADVANCING mnemonic-name phrase cannot be specified when writing a record to 
a file that has a file-description entry (FD) containing the LINAGE clause. . 


The imperative-statement can be the NEXT SENTENCE phrase. 


When an Invalid Key condition occurs, any FILE STATUS data item of the file is set toa 
value indicating the cause of the condition. 
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Segmentation 


Segmentation was designed to enable you to manually divide the PROCEDURE 
DIVISION of a very large program into segments. The segments are stored on disk 
when there is not enough memory to store all the declared data items and the object 
program in main memory. The segments stored on disk are brought into main memory 
when program execution reaches that segment. 


Actual COBOL74 Segmentation 


On A Series systems, the COBOL74 compiler automatically handles program 
segmentation. The compiler normally creates a segment at the beginning of each section 
or at the first paragraph encountered after 1500 words of code have been produced. The 
compiler does not change segments in the middle of a paragraph. Because the maximum 
segment size is 8192 words, you must ensure that no paragraph exceeds this limit. 


If you use segment numbers in section headers, the compiler includes sections with the 
same segment number (other than 0) in one segment. 


Standard COBOL74 Segmentation 


Because many systems are incapable of automatic program-segment overlay, the 
standard COBOL segmentation facility is oriented toward a user-controlled grouping of 
sections into one of three types of segments. This segmentation is based on the value 
of an optional integer (or segment number) following the word SECTION in the section 
header. 


The general format is as follows: 


Section-name SECTION [ segment-number ]. 


The value of the segment-number can range from 0 through 9999, although the system 
allows only a physical maximum of 8192 code segments. If the segment-number 

is omitted from the section header, the value is assumed to be 0. Sections in the 
DECLARATIVES SECTION must declare segment-numbers less than 50. Sections with 
the same segment-numbers need not be adjacent to one another. 


Segments are of three types, depending on the segment-number: fixed permanent, fixed 


overlayable, and independent. Segments with segment-numbers less than 50 belong to 
the fixed portion of the program, which is composed of two types of segments: fixed 
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permanent segments and fixed overlayable segments. The SEGMENT-LIMIT clause in 
the OBJECT-COMPUTER paragraph is used to specify the cutoff point between fixed 
permanent and fixed overlayable segments. 


- The general format of this clause is as follows: 


[ , SEGMENT-LIMIT IS segment-number | 


Explanation of Format 


The distinction between fixed permanent and fixed overlayable is irrelevant in COBOL 
because both types of segments are always made available in their last-used state. Thus, 
the SEGMENT-LIMIT clause is ignored. (This is a Unisys extension.) 


The third type of segment, the independent segment, has segment-numbers ranging 
from 50 through 9999. An independent segment is made available in its initial state 
under the following circumstances: 


e When control is transferred to the segment as a result of an implicit transfer 
of control between consecutive statements from a segment with a different 
segment-number 


e When control is transferred to the segment as a result of an implicit transfer of 
control between a SORT or a MERGE statement in a segment with a different 
segment-number and an input or an output procedure in the independent segment 


e When control is transferred explicitly to the segment with a GO or a PERFORM 
statement from a segment with a different segment-number 


In all other cases, an independent segment is made available in its last-used state. 


Although COBOL conforms to the preceding rules, the use of independent segments 
containing altered GO TO statements can be restricted for the following two reasons 
(Unisys extension): 


e Because code is not modified on Unisys computers, altered GO TO statements are 
handled using references located in the stack of the program. When an independent 
segment must be made available in the initial state, these references must be 
changed to the initial value. 


e Most important, the control path of a program can be changed simply by changing a 
segment-number in a section header. 
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Debugging 


The debug module provides a means for monitoring data item values and 
program-control status during execution of an object program. 


You control the monitoring and display of information on the output device; the debug 
facility simply provides a convenient access to pertinent information. 


The following features support the debug module: 


e Compile-time switch WITH DEBUGGING MODE 
e Object-time switch . 
e USE FOR DEBUGGING statement 

e Special register DEBUG-ITEM 

e _ Debugging lines 


Compile- -Time Switch. 


The WITH DEBUGGING MODE clause is specified in the SOURCE-COMPUTER 
paragraph and serves as a compile-time switch to enable the debugging statements 
written in the program. 


When the WITH DEBUGGING MODE clause is specified, all debugging sections and 
debugging lines are compiled as executable procedures and statements. When the WITH 
DEBUGGING MODE clause is not specified, all debugging lines and debugging sections 


are compiled as comment lines. 


If you are using a debugging line in a program and are compiling the program ¢rom 
CANDE, you must change the FREE compiler control option to FALSE. The FREE 
option is TRUE by default when compiling from CANDE. (This is a Unisys extension.) 


Object-Time Switch 


The DEBUG option of the OPTION task attribute serves as an execution-time switch 

to enable or disable the debugging code enabled by the compile-time switch. The object 
program must be executed with OPTION = DEBUG to enable the debugging code. The 
statement RUN USER/PROGRAM; OPTION = DEBUG is an example of how to set the 
OPTION task attribute. 


The debugging lines are not affected by the use of this execution-time switch. Only those 
items associated with the USE FOR DEBUGGING statement are affected. 
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ENVIRONMENT DIVISION in the Debug Module 


The WITH DEBUGGING MODE clause is specified in the SOURCE-COMPUTER 
paragraph and activates all debugging sections and debugging lines. 


The general format is as follows: 


SOURCE-COMPUTER. computer-name | WITH DEBUGGING MODE ] . 


Explanation of Format 


If the WITH DEBUGGING MODE clause is specified, all USE FOR DEBUGGING 
statements and debugging lines are compiled. 


If the WITH DEBUGGING MODE clause is not specified, the compiler treats any USE 
FOR DEBUGGING statements or debugging lines and all associated debugging sections 
as comment lines. 


PROCEDURE DIVISION in the Debug Module 


The USE FOR DEBUGGING statement identifies the items to be monitored by the 
associated debugging section. 


The general format is as follows: 


section-name SECTION [ segment-number ie USE FOR DEBUGGING ON 
cd-name-1 
{[ ALL REFERENCES OF ] identifier-1 
file-name-1_ 
procedure-name-1 
ALL PROCEDURES 


cd-name-2 

[ ALL REFERENCES OF ] identifier-2 
, « file-name-2 

procedure-name-2 

ALL PROCEDURES 
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Explanation of Format 


Debugging sections, if specified, must appear together, immediately after the 
DECLARATIVES SECTION header. 


Except in the USE FOR DEBUGGING statement itself, no reference can be made to 
any nondeclarative procedure in the debugging section. 


Statements appearing outside the set of debugging sections must not reference 
procedure-names defined in the set of debugging sections. 


Except for the USE FOR DEBUGGING statement itself, statements appearing in a 
given debugging section can reference procedure-names defined in a different USE 
procedure only by using a PERFORM statement. 


Procedure-names defined in debugging sections must not appear in USE FOR 
DEBUGGING statements. 


Any identifier, cd-name, file-name, or procedure-name can appear in only one USE FOR 
DEBUGGING statement and can appear only once in that statement. 


The ALL PROCEDURES phrase can appear only once in a program. 


When the ALL PROCEDURES phrase is specified, procedure-name-1, 
procedure-name-2, and so forth must not be specified in any USE FOR DEBUGGING 
statement. 


Identifier-1, identifier-2, and so on must not refer to any data item defined in the 
REPORT SECTION except sum counters, and must not refer to any item in the 
_ DATA-BASE SECTION. Refer to Volume 2 for information about data management. 


If the data-description entry of the data item referenced by identifier-1, identifier-2, 
and so forth contains an OCCURS clause or is subordinate to a data-description entry 
that contains an OCCURS clause, then identifier-1, identifier-2, and so forth must be 
specified without the subscripting or indexing normally required. 


References to the special register DEBUG-ITEM are restricted to references in a 
debugging section. 


General Rules 
In the following general rules, all references to cd-name-1, identifier-1, procedure- 
name-1, and file-name-1 also apply to cd-name-2, identifier-2, procedure-name-2, and 


file-name-2, respectively. 


Automatic execution of a debugging section is not caused by a statement appearing in a 
_ debugging section. 
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When file-name-1 is specified in a USE FOR DEBUGGING statement, that debugging 
section is executed at each of the following times: 


e After execution of any OPEN or CLOSE statement that references file-name-1 


e After execution of any READ statement (and after any other specified USE 
procedure) not resulting in execution of an associated AT END or INVALID KEY 
imperative-statement 


e After execution of any DELETE or START statement that references file-name-1 


When procedure-name-1 is specified ina USE FOR DEBUGGING statement, that 
debugging section is executed at each of the following times: 


e Immediately before each execution of the named procedure 


e Immediately after execution of an ALTER statement that references 
procedure-name-1 


The ALL PROCEDURES phrase causes the effects described previously for 
procedure-name-1 to occur for every procedure-name in the program except those 
appearing in a debugging section. 


When the ALL REFERENCES OF identifier-1 phrase is specified, that debugging 
section is executed for every statement that explicitly references identifier-1 at each of 
the following times: 


e Ina WRITE or a REWRITE statement, immediately before execution of that 
WRITE or REWRITE statement and after execution of any implicit move resulting 
from the presence of the FROM phrase 


e InaGOTO statement with a DEPENDING ON phrase, immediately before control 
is transferred and before the execution of any debugging section associated with the 
procedure-name to which control is to be transferred 


e Ina PERFORM statement in which a VARYING, an AFTER, or an UNTIL phrase 
references identifier-1, immediately after each initialization, modification, or 
evaluation of identifier-1 


e Inany other COBOL statement, immediately after execution of that statement: 


When identifier-1 is specified without the ALL REFERENCES OF phrase, that 
debugging section is executed at each of the following times: 


e Ina WRITE ora REWRITE statement that explicitly references identifier-1, 
immediately before execution of that WRITE or REWRITE statement and after 
execution of any implicit move resulting from the presence of the FROM phrase 


e Ina PERFORM statement in which a VARYING, an AFTER, or an UNTIL phrase 
references identifier-1, immediately after each initialization, modification, or 
evaluation of identifier-1 


e Inany other COBOL statement, immediately after execution, if it explicitly 
references the data item referenced by identifier-1 and causes the contents to be 
changed 
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If identifier-1 is specified i in a phrase that is not executed or evaluated, the associated 
debugging section is not executed. 


The associated debugging section is not executed for a specific operand more than once 
as a result of the execution of a single statement, regardless of the number of times that 
operand is explicitly specified. Ina PERFORM statement that causes iterative execution 
of a referenced procedure, the associated debugging section is executed once for each 
iteration. 


In an imperative-statement, each individual occurrence of an imperative verb identifies a 
separate statement for debugging purposes. 


When cd-name-1 is specified ina USE FOR DEBUGGING statement, that debugging 
section is executed at each of the following times: 


e After execution of any ENABLE, DISABLE, or SEND statement that references 
cd-name-1 


e After execution of a RECEIVE statement referencing cd-name-1 that does not oe 
in execution of the NO DATA imperative-statement 


e After execution of an ACCEPT MESSAGE COUN rT statement that references 
' ed-name-1 


A reference to file-name-1, identifier-1, procedure-name-1, or cd-name-1 as a qualifier 


does not constitute a reference to that item for debugging, as described in the preceang 
general rules. 


DEBUG-ITEM Special Register 


The reserved word DEBUG-ITEM is the name of a special register that is generated 
automatically. Only one DEBUG-ITEM reserved word is allocated for each program. 
The names of the subordinate data items in DEBUG-ITEM are also reserved words. 
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The special register DEBUG-ITEM is associated with each execution of a debugging 
section. This register provides information about the conditions that caused execution 
of a debugging section. The DEBUG-ITEM special register has the implicit description 
shown in Example 11-1. 


91 DEBUG-ITEM. 
@2 DEBUG-LINE — PIC X(6). 


@2 FILLER PIC X VALUE SPACE. 

62 DEBUG-NAME PIC X(3@). 

62 FILLER PIC X VALUE SPACE. 

@2 DEBUG-SUB-1 PIC $9999 SIGN IS LEADING SEPARATE CHARACTER. 
@2 FILLER PIC X VALUE SPACE. 

92 DEBUG-SUB-2 PIC $9999 SIGN IS LEADING SEPARATE CHARACTER. 
@2 FILLER PIC X VALUE SPACE. 

@2 DEBUG-SUB-3 PIC $9999 SIGN IS LEADING SEPARATE CHARACTER. 


@2 FILLER PIC X VALUE SPACE. 
@2 DEBUG-CONTENTS PIC X(n). | 


Example 11-1. Implicit Description of DEBUG-ITEM Special Register — 


Before each execution of a debugging section, the contents of the data item referenced 
by the reserved word DEBUG-ITEM are space-filled. The contents of data items 
subordinate to DEBUG-ITEM are then updated immediately before control is passed 
to that debugging section. The contents of any data item not specified in the following 
general rules remain space-filled. 


Updating occurs according to the rules for the MOVE statement. The sole 

exception is the move to the DEBUG-CONTENTS item, which is treated as an 
alphanumeric-to-alphanumeric elementary move with no conversion of data from one 
form of internal representation to another. 


The DEBUG-LINE data item identifies the particular source statement that caused the 
debugging section to be executed. The DEBUG-LINE item contains the line number of 
the source image. 


The DEBUG-NAME data item contains the first 30 characters of the name that caused 
the debugging section to be executed. 


All qualifiers of the name are separated in the DEBUG-NAME item by the word OF. 
Subscripts or indexes, if any, are not entered into the. DEBUG-NAMB item. 


If the reference to a data item that causes the debugging section to be executed 
is subscripted or indexed, the occurrence number of each level is entered in the 
DEBUG-SUB-1, DEBUG-SUB-2, and DEBUG-SUB-3 data items, as necessary. 


If the data item is subscripted with more than three subscripts or indexes, only the 
occurrence numbers of the first three levels are entered into the DEBUG-ITEM item. 
(This is a Unisys extension.) 


The DEBUG-CONTENTS data item is large enough to contain the data required by the 
following general rules. | 
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If the first execution of the first nondeclarative procedure in the program causes the 
debugging section to be executed, the following conditions result: 

e The DEBUG-LINE item identifies the first statement of that procedure. 

e The DEBUG-NAME item contains the name of that procedure. 

e The DEBUG-CONTENTS item contains the START PROGRAM statement. 


' Ifa reference to procedure-name-1 in an ALTER statement causes the debugging section 
to be executed, the following conditions result: 


e The DEBUG-LINH item identifies the ALTER statement that references 
procedure-name-1. 

e The DEBUG-NAME item contains procedure-name-1. 

e The DEBUG-CONTENTS item contains the applicable procedure-name associated 
with the TO phrase of the ALTER statement. 


If the transfer of control associated with the execution of a GO TO statement causes the 
debugging section to be executed, the following conditions result: 


e The DEBUG-LINE item identifies the GO TO statement that transfers control to 
procedure-name-1 when executed. . 

e The DEBUG-NAME item contains procedure-name-1. 

If the reference to procedure-name-1 in the INPUT or the OUTPUT phrase of a SORT 


or a MERGE statement causes the debugging section to be executed, the following 
conditions result: 


e The DEBUG-LINE item identifies the SORT or the MERGE statement that 
references procedure-name-1. 

e The DEBUG-NAME item contains procedure-name-1. 

e The DEBUG-CONTENTS item contains the following: 


- The SORT INPUT statement if the reference to procedure-name-1 is in the 
INPUT phrase of a SORT statement 


- The SORT OUTPUT statement if the reference to procedure-name-1 is in the 
OUTPUT phrase of a SORT statement 


- The MERGE OUTPUT statement if the reference to procedure-name-1 is in the 
OUTPUT phrase of a MERGE statement 
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If the transfer of control from the control mechanism associated with a PERFORM 
statement causes the debugging section associated with procedure-name-1 to be 
executed, the following conditions result: 


e The DEBUG-LINE item identifies the PERFORM statement that references 
procedure-name-1. 

e The DEBUG-NAME item contains procedure-name-1. 

e The DEBUG-CONTENTS item contains the PERFORM LOOP statement. 


If procedure-name-1 is a USE procedure that is to be executed, the following conditions 
result: 


e The DEBUG-LINE item identifies the statement that causes execution of the USE. 
procedure. 
e The DEBUG-NAME item contains procedure-name-l. 


e The DEBUG-CONTENTS item contains the USE PROCEDURE statement. 


If an implicit transfer of control from the previous sequential paragraph to 


_ procedure-name-1 causes the debugging section to be executed, the following conditions 


result: 


e The DEBUG-LINE item identifies the previous statement. 
e The DEBUG-NAME item contains procedure-name-1. 
e The DEBUG-CONTENTS item contains the FALL THROUGH statement. 


If references to a file-name-1 or a cd-name-1 data item cause the debugging section to be 
executed, the following conditions result: 


e The DEBUG-LINE item identifies the source statement that references a 
file-name-1 or a cd-name-1 data item. 


e The DEBUG-NAME item contains the name of the file-name-1 or the cd-name-1 
data item. 


e Fora READ statement, the DEBUG-CONTENTS item contains the entire record 
read. | 


e For all other references to file-name-1, the DEBUG-CONTENTS item contains 
spaces. 


e For any reference to cd-name-1, the DEBUG-CONTENTS item contains the 
contents of the area associated with the cd-name. 


If a reference to identifier-1 causes the debugging section to be executed, the following 
conditions result: 

e The DEBUG-LINE item identifies the source statement that references identifier-1. 
e The DEBUG-NAME item contains the name of identifier-1. 


e The DEBUG-CONTENTS item contains the contents of identifier-1 at the time 
control passes to the debugging section. 
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Debugging Lines 


A debugging line is any line with the letter D in the indicator area of the line. Any 
debugging line consisting solely of spaces from margin A to margin R is considered a 
blank line. 


A debugging line is considered a comment line if the WITH DEBUGGING MODE clause 
is not specified in the SOURCE-COMPUTER paragraph. The contents of a debugging 
line must be such that a syntactically correct program is formed whether or not the 
debugging lines are considered comment lines. 


Successive debugging lines are allowed. 


A debugging line is ae in the program only after the OBJECT- COMPUTER 
paragraph. 


Debug Module Program Sample 


Example 11-2 uses the debug module to produce the output shown in Figure 11-1. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DEBUGTEST. 


This program is an example of the COBOL74 debug module. 

Note that the WITH DEBUGGING MODE statement in the SOURCE- 
COMPUTER paragraph instructs the compiler to compile debugging 
statements into the object code. Setting OPTION = DEBUG 

at run time enables the effects described in 

the USE FOR DEBUGGING statement. 


+ + FH F HF 


ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. B79@@ WITH DEBUGGING MODE. 

OBJECT-COMPUTER. B79@8. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

SELECT PRINTFILE ASSIGN TO PRINTER. 

D SELECT DBGFILE ASSIGN TO PRINTER. 

DATA DIVISION. 

FILE SECTION. 

FD PRINTFILE. 


‘G1 PRINT-REC PIC X(132). 

D FD ODBGFILE. 

D @1 DEBUG-REC PIC X(132). 
WORKING-STORAGE SECTION. 
77 ~ALFA PIC 9 VALUE 4. 
77 ~BRAVEO PIC 99 VALUE 16. 
77 ~CHARLIE PIC 99. 

D 77 FLAG PIC 9. 


D 88 NEED-IT VALUE ZERO. 
Example 11-2. Debug Module Sample Program 
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* 


* 


+ + + FF FF F F F F F HF FF F HF F 


88 FILE-OPEN — VALUE 1. 
@1 BARBARA. 
@3 CHERYL. 
@5 DIANNE PIC 99 VALUE 16. 
77, ANN PIC 9(1) VALUE 8. 
77. ELVA . PIC 9(18) . 
77. FRAN PIC -X(32) VALUE "TEST PROGRAM FOR COBOL74 MANUAL". 
77. GOLDIE PIC 9 VALUE 1. 
@1 HIEDI. 
@3 ILENE PIC 9(8) OCCURS 5 TIMES. 
Q3 JANIS PIC 9. 


PROCEDURE DIVISION. 

DECLARATIVES. 

D-BUG SECTION. 

USE FOR DEBUGGING ON 

ALL REFERENCES OF CHARLIE 
ALL REFERENCES OF BRAVEO 
ALL PROCEDURES. 

RECORD DESCRIPTION FOR DEBUG-ITEM. 


@1 DEBUG-ITEM. 


Q2 DEBUG-LINE PIC X(6). 

@2 FILLER PIC X VALUE SPACE. 

Q2 DEBUG-NAME PIC X (38). 

G2. FILLER PIC X VALUE SPACE. 

92 DEBUG-SUB-1 PIC $9(4) SIGN IS LEADING 

| | | SEPARATE CHARACTER. 

@2 FILLER . PIC X VALUE SPACE. 

@2 DEBUG-SUB-2 PIC $9(4) SIGN IS LEADING 
SEPARATE CHARACTER. 

@2 FILLER PIC X VALUE SPACE. 

G2 DEBUG-SUB-3 PIC $9(4) SIGN IS LEADING 
SEPARATE CHARACTER. 

@2 FILLER 3 PIC X VALUE SPACE. 

Q2 DEBUG-CONTENTS PIC X(n). 

DEBUG-OUT. 
IF NEED-IT 


OPEN OUTPUT DBGFILE. 
MOVE 1 TO FLAG. 
WRITE DEBUG-REC FROM DEBUG-ITEM. 
END DECLARATIVES. 
WORK SECTION. 
START-IT. 
SUBTRACT ALFA FROM BRAVEO GIVING CHARLIE. 
DIVIDE BRAVEO BY CHARLIE GIVING ALFA. 
SUBTRACT ALFA FROM BRAVEO GIVING CHARLIE. 
FOLLOW-UP. 
SUBTRACT 4 FROM ANN. 
DIVIDE ANN INTO DIANNE GIVING JANIS. 


Example 11-2: Debug Module Sample Program (cont.) 
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ACCEPT ILENE (GOLDIE) FROM TIME. 
OPEN OUTPUT PRINTFILE. 
WRITE PRINT-REC FROM FRAN. 
“WRITE PRINT-REC FROM ILENE(GOLDIE). 
WRITE PRINT-REC FROM JANIS. 
CLOSE-SHOP. 
CLOSE PRINTFILE RELEASE. 
D . IF FILE-OPEN 
D CLOSE DBGFILE RELEASE. 
STOP RUN. 


Example 11-2. Debug Module Sample Program (cont.) 


Figure 11—1 shows output from the debug module sample program when it is run with 
OPTION = DEBUG. . 


158888 WORK START PROGRAM 
159028 START-IT START PROGRAM 
15@@@@ CHARLIE 12 
158022 BRAVEO 16 
152008 CHARLIE . 7 3 12 
152888 BRAVEO 16 

_ 154900 CHARLIE 15 
154808 BRAVEO 160 
154908 FOLLOW-UP FALL THROUGH 
168828 CLOSE-SHOP FALL THROUGH 


Figure 11-1. Debugging Output from Debug Module Sample Program 
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Report Writer 


Report Writer is a special-purpose language subset of COBOL that provides a convenient 
way to produce reports. 


The file-description (FD) entry for Report Writer requires a REPORT clause to name 
the reports that are created. The other FD clauses that can be used are described in 
Section 7, “DATA DIVISION.” 


Most of the coding required for Report Writer is in describing the data. The REPORT 
SECTION of the DATA DIVISION defines the logical organization, format, contents, 
_and structure of the report. A hierarchy of levels defines the logical organization. Each 
report consists of report groups; these groups are divided into sequences of items. 


Using the report description (RD) in the REPORT SECTION, the compiler automatically 
generates PROCEDURE DIVISION code. This code moves data, constructs print lines, 
counts line and page numbers, produces heading and footing lines, sums pu Onna HOH, and 
checks control breaks. 


Example 12-1, which appears at the end of this section, is a complete program that 
illustrates many of the features of Report Writer. 


FILE SECTION REPORT Clause 


In the FILE SECTION, Report Writer requires the REPORT clause to list the names of 
the reports to be produced. 


The general format is as follows: 


FILE SECTION. 


REPORT IS 
ED report-file | eepORT ARE 


\ report-name-1 [ , report-name-2 ] .. 


Explanation of Format 


‘ report-file 


Report-file identifies the file to which reports are written when a GENERATE statement 
is executed. 
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A report-file can be referenced only by the OPEN OUTPUT statement or by the CLOSE 
statement. 


After the execution of an INITIATE statement and before the execution of a 
TERMINATE statement for the same report file, no other explicit I/O operation can 
reference that report file or the record-description (RD) entries associated with it. (This 
is a Unisys extension.) 


REPORT or REPORTS 
The REPORT clause specifies the names of reports that make up a report file. 


More than one report-name in a REPORT clause indicates that the report file contains 
more than one report. 


report-name 


Each report-name specified ina REPORT clause must be the subject of a 
report-description (RD) entry in the REPORT SECTION. The order of appearance of 
the report-names is not significant. A report-name must appear in only one REPORT 
clause. 


REPORT SECTION Report-Description Entry 


The REPORT SECTION includes a report-description (RD) entry and one or more 
report group descriptions. 


The RD entry describes the general organization of the report, including the layout of 
elements on a page. This entry is uniquely identified in the REPORT SECTION by the 
level indicator RD. The RD entry is analogous to the FD entry in the FILE SECTION. 


The report group descriptions provide information about each part of the report and 
about sources of information for the report. The clauses that follow the report-name are 
optional, and the order of appearance is not significant. These clauses are discussed 
separately on the following pages. 


You must use a period at the end of the report-description (RD) entry. 
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The general format is as follows: 
RD report-name 


[ ; CODE literal-1 | 


| leONTEOL IS } ere [ , data-name-2 ]... | 
] 


CONTROLS ARE J [FINAL [, data-name-1[ , data-name-2 ].. 


LIMIT IS LINE 
anne an | a jaar 
, HEADING integer-2 | 
, FIRST DETAIL integer-3 | 


[ , LAST DETAIL integer-4 | 
[ , FOOTING integer-5 | 


Explanation of Format 


RD 


The level indicator RD identifies the beginning of a report description and must precede 
_ the report-name. The report-name must appear in one, and only one, REPORT clause. 


report-name 


Report-name is the highest permissible qualifier that can be specified for 
LINE-COUNTER, PAGE-COUNTER, and all data-names defined in the REPORT 
SECTION. 


CODE Clause (Unisys Extension) 


The CODE clause places a nonnumeric value on each line of the report for identification 
purposes. . 


If more than one report is associated with a file and the reports are produced 


simultaneously, the CODE clause must be used so that the individual lines of each report 
can be identified by the operating system printer-backup routine. 
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The format of the CODE clause is as follows: 


CODE literal-1 


12-4 


Explanation of Format 


CODE 
When the CODE clause is specified, literal-1 is automatically placed in each record 
generated. The positions occupied by literal-1 are not included in the description of the 


print line, but are included in the size of a logical record. 


If the CODE clause is specified for any report in a file, it must be specified for all reports 
in that file. 


literal-1 


Literal-1 must be a 2-character, nonnumeric literal. 


Example 
The following paragraphs detail the use of the CODE clause with WFL. 


The backup printer file that is on disk, for the purpose of producing a report, has the 
following title when the CODE clause is specified: 


BDREPORT/job-number/task-number/count-ID 


The job-number is the mix number assigned to the job that created the report and is 
expressed as a 7-digit number. The task-number is the mix number assigned to the task 
that created the report and is expressed as a 7-digit number. The count is 001 for the 
first time the file is opened within the task, 002 for the second time, and so forth. The 
ID is taken from the VALUE OF TITLE clause specified for the file. For example, if - 


' the job-number is 325 and the task-number is 327 and the VALUE OF TITLE clause 


specifies the value ABCD, then the file title assigned to a backup disk file is 
BDREPORT /@200325 /@000327 /GG1ABCD 

The second time the file is opened within that task, the file title is 
BDREPORT /@220325 /@008327 /O@2ABCD 

The backup disk files can be printed by using either of the following WF'L statements: 
PB D job-number KEY REPORT EQUAL literal-1 


PB D * KEY REPORT EQUAL literal-1 
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Job-number is the 4-digit mix number of the job that created the report. The 

asterisk (*) indicates that the job-number to be used is the job-number of the WF'L job 
itself. The asterisk function is useful a PB (Printer Backup) statement is included in a 
WFL statement that both creates and prints the report. 


When the KEY clause is used in the WF'L statement literal-1 must match literal-1 used 
in the CODE clause. For example: 


PB D @325 KEY REPORT EQUAL "A2" 


The backup tape file of a Report Writer report for which a CODE clause was specified 
can be printed by using the following WFL statement: 


PB MT xxx [FILE integer] KEY REPORT EQUAL literal-1 


In the preceding statement, xxx is the tape unit on which the backup tape resides, and 
literal-1 is used as shown in the backup disk file example. 


When a printer file with an associated CODE clause is opened, the object code generated 
includes instructions to the operating system to set the BDNAME attribute of the 
program task to BDREPORT. In a program that contains multiple printer files— some 

of which contain CODE clauses and some of which do not BDREPORT is used as the 
file title prefix for all files that are opened after a file with an associated CODE clause is 
opened, even if the remaining files do not have associated CODE clauses. If this is not 
the desired result and multiple printer files are required in the program, the printer files 
that do not have an associated CODE clause should be opened before the ones that do. 


CONTROL Clause 


The CONTROL clause specifies the names of the control data items, in order from the 
most significant to the least significant. 


The CONTROL clause is required when control headings, control footings, or both 
groups are used. 


The CONTROL clause establishes the level of the control hierarchy for the report. 


The general format of this clause is as follows: 


encrnn Is } ecu [ , data-name-2 ]... \ 


CONTROLS ARE} (FINAL [, data-name-1 [ , data-name-2 ]...] 


Explanation of Format 


The data-names specified in the CONTROL clause are the only data-names referred 
to by the RESET and TYPE clauses in the report-group descriptions for a report. No 
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data-name, including the word FINAL, can be referenced by more than one CONTROL 
HEADING report group and one CONTROL FOOTING report group. 


The data-names and the word FINAL specify the levels of the control hierarchy. FINAL, 
if specified, is the highest control; data-name-1 is the major control; data-name-2 is an 
intermediate control; and so forth. The last data-name specified is the minor control. 


Data-name-1 and data-name-2 must not be defined in the REPORT SECTION. 
Data-name-1 and data-name-2 can be qualified but must not be subscripted or indexed. 


Each data-name must identify a different data item. 


Data-name-1, data-name-2, and so on must not have subordinate variable-occurrence 
data items. Control data items are subject to the same rules that apply to sort keys. 


Causing a Control Break 


A control break is a change in the value of a data item. The data item, which is 
referenced in the CONTROL clause, controls the hierarchical structure of the report. 


The execution of the first chronological GENERATE statement for a report causes the 
values of all control data items associated with that report to be saved. On subsequent 
executions of all GENERATE statements for that report, Report Writer tests control 
data items for a change of value. A change of value in any control data item causes a 
control break to occur. The control break is associated with the highest level for which a 
change of value is noted. 


Report Writer tests for a control break by comparing the contents of each control data 
item with the prior contents saved from the execution of the previous GENERATE 
statement for the same report. Report Writer applies the relation test as follows: 


@ Ifthe control data item is a numeric data item, the program compares two numeric 
operands. 


e Ifthe control data item is an index data item, the program compares two index data 
items. | | 


e Ifthe control data item is a data item other than a numeric or an index data item, 
the program compares two nonnumeric operands. 


A control break for the word FINAL occurs before the first detail line is printed and 
whenever a TERMINATE statement is executed. A control break occurring at a 
particular level implies a control break for each lower level in the control hierarchy. 
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For example, when control headings and footings are coded, the CONTROL clause 
CONTRGLS ARE MAJ-KEY, INT-KEY, MIN-KEY causes the control headings and 
footings to be printed in the following order on a control break on MAJ-KEY: 


CONTROL FOOTING (for MIN-KEY) 
CONTROL FOOTING (for INT-KEY) 
CONTROL FOOTING (for MAJ-KEY) 
CONTROL HEADING (for MAJ-KEY) 
CONTROL HEADING (for INT-KEY) 
CONTROL HEADING (for MIN-KEY) 


PAGE Clause 
‘The PAGE clause defines the length of a page and the vertical subdivisions within which 
report groups are presented. If the PAGE clause is omitted, the report consists of a 
single page of indefinite length. 
The general format of this clause is as follows: 


PAGE es = i integer-1 ee \ 
“A= | LIMITS ARE LINES 


[, HEADING integer-2 ] | , FIRST DETAIL integer-3 | 


[ , LAST DETAIL integer-4 | | , FOOTING integer-5 | 


Note: The HEADING, FIRST DETAIL, LAST DETAIL, and FOOTING 
phrases can be written in any order. 


Explanation of Format 


_LIMIT IS integer-1 LINES: 


The words LIMIT IS or LIMITS ARE and LINE or LINES are optional and can be 
omitted. 


Integer-1 defines the vertical length of a report page by specifying the number of lines 
available on each page. 


Integer-1 must not be greater than 255. (This is a Unisys extension.) Also, integer-1 
' must be greater than or equal to integer-5. 


Absolute LINE NUMBER or absolute NEXT GROUP spacing must be consistent with 
controls specified in the PAGE LIMIT clause. 
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HEADING 


A heading can be one of the following types: 


Type Purpose . 

REPORT Appears at the beginning of a report only 

PAGE Appears at the beginning of a page 

CONTROL Appears at the beginning of the control group to which it belongs 


The HEADING integer-2 phrase defines the first line number on which a REPORT 
HEADING or PAGE HEADING report group can begin. 


Integer-2 must be greater than or equal to 1. If the HEADING phrase is omitted, a 


value of 1 is assumed for integer-2. 


The following rules indicate the vertical subdivision of the page in which each type of 
report group can appear when the PAGE clause is specified: 


e Ifyou want a REPORT HEADING report group to be on a page by itself, the 
program must define it to be within the vertical subdivision of the page that extends 
from the line number specified by integer-2 to the line number specified by integer-1, 
inclusive. . 


e Ifyou want a REPORT HEADING report group that is not on a page by itself, the 
program must define it to be within the vertical subdivision of the page that extends 
from the line number specified by integer-2 to the line number specified by integer-3 
minus 1, inclusive. 


e Ifyou want aPAGE HEADING report group , the program must define it to be in 
the vertical subdivision of the page that extends from the line number specified by 
integer-2 to the line number specified by integer-3 minus 1, inclusive. 


e Ifyou want aCONTROL HEADING or a DETAIL report group, the program must 
define it to be in the vertical subdivision of the page that extends from the line 
number specified by integer-3 to the line number specified by integer-4, inclusive. 


e Ifthe HEADING phrase is omitted, a value of 1 is assumed for integer-2. 

FIRST DETAIL 

The FIRST DETAIL integer-3 phrase defines the first line number on which a body 
group can begin. REPORT HEADING and PAGE HEADING report groups cannot be 
on or beyond the line number specified by integer-3. 


Integer-3 must be greater than or equal to integer-2. 


If the FIRST DETAIL phrase is omitted, a value equal to integer-2 is given to integer-3. 


LAST DETAIL 


The LAST DETAIL integer-4 phrase defines the last line number on which a CONTROL | 
HEADING or a DETAIL report group can be presented. 
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Integer-4 must be greater than or equal to integer-3. 


If the LAST DETAIL and FOOTING phrases are both omitted, the value of integer-1 is 
given to both integer-4 and integer-5. 


If the LAST DETAIL phrase is specified and the FOOTING phrase is omitted, the value 
of integer-4 is given to integer-5. 


If absolute line spacing is indicated for all report groups, integer-2 through integer-5 
need not be specified. If relative line spacing is indicated for individual detail report 


group entries, some or all of the limits must be defined (depending on the type of report 
groups within the report) for control of page formatting to be maintained. 


FOOTING 


A footing can be one of the following types: 


Type Purpose 

REPORT , Appears at the end of a report only 

PAGE . Appears at the end of a page 

CONTROL Appears at the end of the control group to which it belongs 


The FOOTING integer-5 phrase defines the last line number on which a CUNTROL 
FOOTING report group can be presented. PAGE FOOTING and REPORT FOOTING 
report groups must follow the line number specified by integer-5. 


Integer-5 must be greater than or equal to integer-4. 


If the FOOTING phrase is specified and the LAST DETAIL phrase is omitted, th 2 value 
of integer-5 is given to integer-4. 


The following rules indicate the vertical subdivision of the page in which each type of 
report group can appear when the PAGE clause is specified: 


e Ifyou wanta CONTROL FOOTING report group, the program must define it to be 
_ in the vertical subdivision of the page that extends from the line number specified by 
integer-3 to the line number specified by integer-5, inclusive. 


e Ifyou wanta PAGE FOOTING report group, the program must define it to be in 
the vertical subdivision of the page that extends from the line number specified by 
integer-5 plus 1 to the line number specified by integer-1, inclusive. 


e Ifyou want a REPORT FOOTING report group to be on a page by itself, the 
' program must define it to be in the vertical subdivision of the page that extends from 
the line number specified by integer-2 to the line number specified by integer-1, 
inclusive. 


e Ifyou want a REPORT FOOTING report group that is not on a page by itself, the 
program must define it to be within the vertical subdivision of the page that extends 
from the line number specified by integer-5 plus 1 to the line number ppened by 
integer-1, inclusive. 
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All report groups must be described so that they can be presented on one page. A 
multiline report group is never split across page boundaries. 


General Rules 


Figure 12-1 illustrates page format control of report groups when the PAGE LIMIT 
clause is specified. 


Heading Detail Footing 


Integer-2 
Integer-3 
Integer-4 
Integer-5 


Integer-1 


Figure 12-1. Page Format Control 
The page regions established by the PAGE clause are shown in Table 12-1. 


Table 12-1. Page Regions Established by the PAGE Clause 


Report Groups That Can Be Presented in First Line Number of | __Last Line Number of 
the Region the Region the Region 


REPORT HEADING described with integer-2 integer-1 
NEXT GROUP NEXT PAGE phrase 


REPORT FOOTING described with LINE integer-2 integer-1 
integer-1 NEXT PAGE phrase 


REPORT HEADING not described with integer-2 integer-3 minus 1 
NEXT GROUP NEXT PAGE phrase 


PAGE HEADING integer-2 integer-3 minus 1 
CONTROL HEADING integer-2 integer-4 


DETAIL integer-2 integer-4 
CONTROL FOOTING integer-3 integer-5 
PAGE FOOTING _ integer-5 plus 1 integer-1 


continued 
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Table 12-1. Page Regions Established by the PAGE Clause (cont.) 


Report Groups That Can Be Presented in First Line Number of Last Line Number of 
the Region the Region the Region 


REPORT FOOTING not described with integer-5 plus 1 integer-1 
LINE integer-1 NEXT PAGE phrase 


Special Registers 


The compiler automatically supplies the following two pec registers for each report 
described in the REPORT SECTION: 


e PAGE-COUNTER 
e LINE-COUNTER 


Because the special registers are automatically supplied, you do not have to code 
data-description entries for them. 


PAGE-COUNTER 


PAGE-COUNTER refers to a special register that the compiler automatically creates for 
each report specified in the REPORT SECTION. The purpose of PAGE-COUNTER is to 
provide consecutive page numbers for a report. 


In the REPORT SECTION, a reference to PAGE-COUNTER can appear only 

ina SOURCE clause. Outside the REPORT SECTION, the special register 
PAGE-COUNTER can be used in any context in which a data-name of integral value can 
appear. 


If more than one PAGE-COUNTER exists in a program, PAGE-COUNTER must be 
qualified by a report-name whenever it is referenced in the PROCEDURE DIVISION. 
In the REPORT SECTION, an unqualified reference to PAGE-COUNTER is implicitly 
qualified by the name of the report in which the reference is made; whenever the 
PAGE-COUNTER of a different report is referenced, PAGE-COUNTER must be 
explicitly qualified by that report-name. 


Execution of an INITIATE statement resets to 1 the PAGE-COUNTER for the 
referenced BEpOnes 


PAGE-COUNTER can be altered by PROCEDURE DIVISION statements. If you 


want a starting value other than 1, the program should change the contents of 
PAGE-COUNTER following the INITIATE statement for that report. 
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LINE-COUNTER 


LINE-COUNTER refers to a special register that the compiler automatically creates 
for each report for which the PAGE LIMIT clause is specified. If more than one 
LINE-COUNTER exists in a program, then all references to LINE-COUNTER must be 
qualified. In the REPORT SECTION, an unqualified reference to LINE-COUNTER is 
implicitly qualified by the name of the report in which the reference is made. 


Inthe REPORT SECTION, a reference to LINE-COUNTER can appear only 


ina SOURCE clause. Outside the REPORT SECTION, the special register 
LINE-COUNTER can be used in any context in which a data-name of integral value can 
appear. Changing the LINE-COUNTER by using PROCEDURE DIVISION statements 
can cause page-format control to become unpredictable. 


Execution of an INITIATE statement resets to 0 (zero) the LINE-COUNTER for the 
referenced report. LINE-COUNTER is also reset to 0 each time a page is advanced for 
the associated report. 


After a report group is printed, LINE-COUNTER contains the line number that 
corresponds to the last line of the report group that was printed, unless the report 
group designates the NEXT GROUP clause or the specific line number. In that case, 
LINE-COUNTER contains the value 0 (zero). 


See Also 


For further information on line number positioning, refer to “LINE NUMBER Clause” 
and “NEXT GROUP Clause” later in this section. 


_ REPORT SECTION Report-Group Descriptions 
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_ One or more report groups follow each report-description (RD) entry. Each group 


describes one or more print lines related to a specific function in producing a report. A 
report group is described by a hierarchic data structure similar to record descriptions in 
the other sections of the DATA DIVISION. 

The report-group descriptions can appear only in the REPORT SECTION. 


Except for the DATA-NAME clause (which, when present, must immediately follow the 
level-number), clauses can be written in any sequence. 


The description of a report group can consist of one, two, or three hierarchic levels. 


The report-group descriptions have the following three formats: 


Format Explanation 
1 Describes the 01-level of the report group. 
2 Describes a single line of the report group. This format must be followed 


immediately by Format 3 entries that describe the items to be printed on the line. 


3 Describes the items to be printed on a line, or describes a line that contains only 
one item to be printed. 
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Format 1 Report-Group Descriptions 


Format 1 describes the 01-level of the report group. The first entry of a report group 
must be a Format 1 entry, which is as follows: 
01 [ data-name-1 | 


| - LINE NUMBER IS saan ON NEXT ee 


PLUS integer-2 


integer-3 
; NEXT GROUP IS fe nies | 
NEXT PAGE 


REPORT. aaa 


PAGE HEADING 


data-name-2 
FINAL 


data-name-3 
FINAL 


EPORT FOOTING | 


GE FOOTING | 


[ ; USAGE IS DISPLAY ]. 


Explanation of Format 1 


In this format, the integers must be greater than 0. 
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data-name-1 


Data-name-1 of a Format 1 entry can be referenced only by a GENERATE statement, 
the UPON phrase of a SUM clause, a USE BEFORE REPORTING statement, or as a 
sum-counter qualifier. Data-name-1 is required in a Format 1 entry only in the following 
cases: 

e Whena DETAIL report group is referenced by a GENERATE statement 

e When a DETAIL report group is referenced by the UPON phrase of a SUM clause 

e When areport group is referenced ina USE BEFORE REPORTING sentence _ 


e When the name of aCONTROL FOOTING report group is used to qualify a 
reference to a sum counter 


LINE NUMBER Clause 
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The LINE NUMBER clause specifies information about the vertical Epes of the 
report group. 


A LINE NUMBER clause must be specified to establish each print line of a report group. 


Every entry that defines a printable item must either contain a LINE NUMBER clause 
or be subordinate to an entry that contains a LINE NUMBER clause. 


An entry that contains a LINE NUMBER clause must not have a subordinate entry that 
also contains a LINE NUMBER clause. 


Explanation of LINE NUMBER Clause Format 


integer-1 

Integer-1 specifies the absolute line number on which the print line is printed. 
Integer-1 must not exceed 3 significant digits in length. 

Integer-1 cannot be specified in a way that would cause any line of a report group to be 


presented outside the vertical page subdivision which is defined for that a al group 
type by the PAGE clause. 


integer-2 

Integer-2 specifies a relative line number. Ifa relative LINE NUMBER clause is 
specified, the line number on which the print line is printed is determined by the sum 
of the line number on which the previous print line of the report group was printed and 
integer-2 of the relative LINE NUMBER clause. 


Integer-2 must not exceed 8 significant digits in length. 
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Integer-2 cannot be specified in a way that would cause any line of a report group to be 
presented outside the vertical page subdivision designated for that report group type as 
defined by the PAGE clause. 


NEXT PAGE 


The NEXT PAGE phrase specifies that the report group is to be presented beginning on 
the indicated line number on a new page. 


A NEXT PAGE phrase can appear only once. If present, this phrase must be in the first 
LINE NUMBER clause. A LINE NUMBER clause with the NEXT PAGE phrase can 
appear only in the description of body groups and ina REPORT FOOTING report group. 


General Rules 
All absolute LINE NUMBER clauses must precede all relative LINE NUMBER clauses. 


Successive absolute LINE NUMBER clauses must specify integers in ascending order. 
The integers need not be consecutive. 


If the PAGE clause is omitted, only relative LINE NUMBER clauses can be specified in 
any report-group description entry in the report. 


The vertical positioning specified by a LINE NUMBER clause occurs before the line 
established by that LINE NUMBER clause is printed. 


The first LINE NUMBER clause specified within a PAGE FOOTING report group must 
‘be an absolute LINE NUMBER clause. 

NEXT GROUP Clause 
The NEXT GROUP clause specifies information for vertical positioning of a page 
following the presentation of the last line of a report group. A report-group description 
entry must not contain a NEXT GROUP clause unless the a oa of that report 
group contains at least one LINE NUMBER clause. 


Integer-3 and integer-4 must not exceed the value 255. (Thisisa Unisys extension.) 


If the PAGE clause is omitted from the report-description entry, only a relative NEXT 
_ GROUP clause can be specified in any report-group description entry in that report. 


The NEXT PAGE phrase of the NEXT GROUP clause must not be specified in a PAGE 
FOOTING report group. 


The NEXT GROUP clause must not be specified ina REPORT FOOTING report group 
or ina PAGE HEADING report group. 
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General Rules 


Integer-3 specifies the absolute line on which the next group is printed. The PLUS 
phrase designates the number of lines after the current line on which the next group is 
printed. The NEXT PAGE phrase prints the next group on the next page. 


Any positioning of the page specified by the NEXT GROUP clause takes oes after the 
report group in which the clause appears is printed. 


The vertical positioning information supplied by the NEXT GROUP clause is interpreted 
along with information from the TYPE and PAGE clauses and the value in the 
LINE-COUNTER special register. This information is used to determine a new value for 
LINE-COUNTER. 


~The NEXT GROUP clause is ignored when it is specified on a CONTROL FOOTING 


report group that is at a level other than the highest level at which a control break is 
detected. 


The NEXT GROUP clause of a body group refers to the next body group to be printed 
and, therefore, can affect the location at which the next body group is printed. The 
NEXT GROUP clause of a REPORT HEADING report group can affect the location at 
which the PAGE HEADING report group is printed. The NEXT GROUP clause of a 
PAGE FOOTING report group can affect the location at which the REPORT FOOTING 
report group is printed. 


TYPE Clause 
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The TYPE clause specifies the particular type of report group described by this | 
report-group description and indicates the time at which the report group is to be 
processed. This clause is a required entry in Format 1. 


REPORT HEADING, PAGE HEADING, CONTROL HEADING FINAL, CONTROL 
FOOTING FINAL, PAGE FOOTING, and REPORT FOOTING report groups can 
appear no more than once in the description of a report. 


Explanation of TYPE Clause Format 


data-name-2, data-name-3, and FINAL 


If present, these data items must be specified in the CONTROL clause of the 
corresponding report-description entry. At most, one CONTROL HEADING report 
group and one CONTROL FOOTING report group can be specified for each data-name 
or FINAL option in the CONTROL clause of the report-description entry. However, 
neither a CONTROL HEADING report group nor a CONTROL FOOTING report group 
is required for a data-name or a FINAL option specified in the CONTROL clause of the 
report-description entry. 
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In CONTROL FOOTING, PAGE HEADING, PAGE FOOTING, and REPORT 
FOOTING report groups, the SOURCE clauses and the USE statements must not 
reference any of the following: 


e Group data items containing a control data item 
e Data items subordinate to a control data item 
e Aredefinition or renaming of any part of a control data item 


In PAGE HEADING and PAGE FOOTING report groups, the SOURCE clauses and the 
USE statements must not reference control data-names. 


REPORT HEADING or RH 


The REPORT HEADING phrase specifies a report group that is processed only once for 
each report as the first report group of that report. The REPORT HEADING report 
group is processed during the execution of the first chronological GENERATE statement 
for that report. 


PAGE HEADING or PH 


- The PAGE HEADING phrase specifies a report group that is processed as the first 
report group on each page of that report, except under the following conditions: 


e APAGE HEADING report group is not processed on a page that is to contain only a 
REPORT HEADING report group or only a REPORT FOOTING report group. 


e APAGE HEADING report group is processed as the second report group on a page 
when it is preceded by a REPORT HEADING report group that is not to be printed 
on a page by itself. 


e PAGE HEADING report groups can be snedficd ae if a PAGE clause is specified in 
the corresponding report-description entry. 


CONTROL HEADING or CH — 


The CONTROL HEADING phrase specifies a report group that is processed at the 
beginning of a control group for a designated control data-name or, in the case of the 
FINAL option, is processed during execution of the first chronological GENERATE 
statement for that report. If a control break is detected during the execution of any 
GENERATE statement, any CONTROL HEADING report groups associated with the 
highest level of the control break and lower levels are processed. 


_ DETAIL or DE 


The DETAIL report groups are processed as a direct result of GENERATE statements. 
If a report group is other than type DETAIL, processing is an automatic function. 


The DETAIL phrase specifies a report group that is processed when a corresponding 
GENERATE statement is executed. - 


8600 0296-000 7 12-17 


Report Writer 


CONTROL FOOTING or CC 


The CONTROL FOOTING phrase specifies a report group that is processed at the end 
of a control group for a designated control data-name. In the case of the FINAL option, 
the CONTROL FOOTING report group is processed only once for each report, as the 
last body group of that report. During execution of any GENERATE statement in which 
a control break is detected, any CONTROL FOOTING report group associated with the 
highest level of the control break or with more minor levels is printed. All CONTROL 
FOOTING report groups are printed during execution of the TERMINATE statement if 
at least one GENERATE statement has been executed for the report. 


PAGE FOOTING or PF 


The PAGE FOOTING phrase specifies a report group that is processed as the last report 
group on each page, except under the following conditions: 


e APAGE FOOTING report group is not processed on a page that is to contain only a 
REPORT HEADING report group or only a REPORT FOOTING report group. 


e APAGE FOOTING report group is processed as the second-to-last report group on 
a page when it is followed by a REPORT FOOTING report group that is not to be 
processed on a page by itself. 


e PAGE FOOTING report groups can be specified only if a PAGE clause is specified in 
the corresponding report-description entry. 


REPORT FOOTING or RF 
The REPORT FOOTING phrase specifies a report group that is processed only once for 
each report as the last report group of that report. The REPORT FOOTING report 


group is processed during the execution of a corresponding TERMINATE statement if at 
least one GENERATE statement has been executed for the report. 


_USAGE Clause (Report Writer) 


A USAGE clause specifies the format of a data item in computer storage. 
The USAGE clause can be used at either the elementary level or 01-level; however, the 


USAGE clause of all report groups and their elementary items must be the same as the 
USAGE clause of the file on which the report is written. 


See Also 


For a detailed description of the USAGE Te refer to “USAGE Clause” in Section 7, 
“DATA DIVISION.” 
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Processing Report Groups 


The sequence of steps executed when REPORT HEADING, PAGE HEADING, 
CONTROL HEADING, PAGE FOOTING, or REPORT FOOTING report groups are 
processed as discussed in the following list: 


1. Ifa USE BEFORE REPORTING procedure is present that references the 
data-name of the report group, the USE procedure is executed. 


2. Ifthe report group is not printable, no further processing is done for the report 
group. 


3. Otherwise, the print lines are formatted and printed according to the rules for the 
given type of report group. 


Processing a CONTROL FOOTING Report Group 


The sequence of steps executed when a CONTROL FOOTING report group is processed 
is described in the following list: 


The GENERATE statement rules specify that when a control break occurs, the 
CONTROL FOOTING report groups, beginning at the minor level and proceeding 
upwards, are processed through the level at which the highest control break was 
detected. Although no CONTROL FOOTING report group has been defined for a given 
control data-name, step 5 in the following procedure is executed if a RESET phrase 
within the report description (RD) specifies that control data-name. 


1. Sum counters are crossfooted; all sum counters defined in this report group that are 
operands of SUM clauses in the same report group are added to the sum counters. 


2. Sum counters are rolled forward; that is, all sum counters defined in this report 
group that are operands of SUM clauses in higher-level CONTROL FOOTING 
report groups are added to the higher-level sum counters. 


3. Ifa USE BEFORE REPORTING procedure references the data-name of the report 
group, the USE procedure is executed. 


4. Ifthe report group is not printable, step 5 is executed next; otherwise, the print 
lines are formatted and the report group is printed according to the rules for 
CONTROL FOOTING report groups. 


5. Sum counters that are to be reset when this level is processed in the control 
hierarchy are reset. . 


Processing a DETAIL Report Group 


The following five steps describe the detail-related processing that is executed in 
response to a GENERATE report-name statement when the description of the 
report includes exactly one DETAIL report group. These steps are performed as if a 
GENERATE data-name statement were being executed. 
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When the description of a report includes no DETAIL report groups, the detail-related 
processing in response toa GENERATE report-name statement is executed as described 
in step 1. This step is performed as if the description of the report included exactly one 
DETAIL report group and a GENERATE data-name statement were being executed. 


1. Any subtotaling designated for the DETAIL report group is performed. 


2. Ifa USE BEFORE REPORTING procedure refers to the data-name of the report 
group, the USE procedure is executed. 


3. Ifthe report group is not printable, no further processing is done for the report — 
group. 

4. Ifthe DETAIL report group is processed as a consequence ofa GENERATE . 
report-name statement, no further processing is done for the report group. 


5. Ifthese conditions are not applicable, the print lines are formatted, and the report 
group is printed according to the rules for DETAIL report groups. 


Processing After Printing a Body Group 


When a CONTROL HEADING, a CONTROL FOOTING, or a DETAIL report is 
processed, interruption of a previously described processing of that body group might 
be necessary after determining that the body group is to be printed. A page advance is 
executed (and PAGE FOOTING and PAGE HEADING report groups are processed) 
before the body group is actually printed. 


During control-break processing, the values of control data items used to detect a given 
control break are known as prior values. The following rules apply to prior values: 


e During control-break processing of a CONTROL FOOTING report group, any 
references to control data items in a USE procedure or a SOURCE clause associated 
with that CONTROL FOOTING report group are supplied with prior values. 


e Whena TERMINATE statement is executed, the prior value for the control data 
item are made available to a SOURCE clause or USE procedure references in 
CONTROL FOOTING and REPORT FOOTING report groups as if a control break 
were detected in the highest control data-name. 


e Allother data item references in report groups and USE procedures access the 
current values contained in the data items when the report group is processed. 


_ Format 2 Report-Group Descriptions 


A Format 2 entry describes a single line of the report group and must be followed 
immediately by Format 3 entries describing the printable items for the line. 
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The general format of this clause is as follows: 


level-number [ data-name-1 ] 


; LINE NUMBER IS { 


integer-1| ON NEXT PAGE] \ 
PLUS integer-2 


[ ; [USAGE IS ] DISPLAY}. 


Explanation of Format 2 
The level-number in Format 2 can be any integer between 02 and 48, inclusive. 


Data-name-1 is optional. If present, it can be used eal to qualify a sum-counter 
reference. 


A Format 2 entry must contain at least one of the optional clauses. 


LINE NUMBER 
The LINE NUMBER clause specifies vertical positioning information for its report 


group. A LINE NUMBER clause must be used to establish each print line of a report 
group. 


USAGE (Report Writer) 
A USAGE clause specifies the format of a data item in computer storage. 
The USAGE clause can be used at the elementary item level. The usage of all 


elementary items must be the same as the usage of the file on which the report is 
written. 


See Also 


For a detailed description of the USAGE clause, refer to “USAGE Clause” in Section 7, 
“DATA DIVISION.” 


For more details about the LINE NUMBER clause, refer to Format 1 earlier in this 
section. 
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Format 3 Report-Group Descriptions (Unisys Extension) 


Format 3 entries, besides describing a single, printable item of a line, can also be used to 
describe a line that contains only one printable item. 


The general format of this clause is as follows: 


level-number [ data-name-1] 

[ ; BLANK WHEN ZERO] 

[ ; COLUMN NUMBER IS integer-3] 
[ | GROUP INDICATE] 


. 


ee } RIGHT | 


| ; LINE NUMBER IS { 


integer-1 ON NEXT PAGE 
PLUS integer-2 


PICTURE 
; {Bi IS character-string 
PC 


; SOURCE IS i : 
| identifier-1 


; SUM identifier-2 [ , identifier-3 ]... 
{ [ UPON data-name-2 [ , data-name-3 ] ...] } ° 


samo 


data-name-4 
VALUE : 


TODAYS-DATE } 


[ ; [USAGE IS ] DISPLAY ]. 
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Explanation of Format 3 


In this format, the integers must be greater than 0. 


level-number — 


The level-number in Format 3 can be any integer between 02 and 49, inclusive. 


data-name-1 


Data-name-1 is optional and can be referenced only if the entry defines a sum counter. 


‘BLANK WHEN ZERO Clause 


The BLANK WHEN ZERO clause controls printing of spaces when the value of a data 
item is 0 (zero). The rules for using this clause in Report Writer are the same as those © 
described for the clause in Section 7, “DATA DIVISION.” 


COLUMN NUMBER Clause 


The COLUMN NUMBER clause identifies an item to be printed and specifies the 
horizontal position of the item on the print line. 


The absence of a COLUMN NUMBER clause indicates that the entry is not to be 
printed. 


The COLUMN NUMBER clause indicates that the object of a SOURCE clause, the 
object of a VALUE clause, or the sum counter defined by a SUM clause is to be printed 
with the leftmost character position indicated by integer-3. 


The COLUMN NUMBER clause can be specified only at the elementary level. When 
this clause is used, it must appear in, or be subordinate to, an entry that contains a LINE 
NUMBER clause. 


Integer-3 specifies the leftmost character position of the printable item. It is important 
to ensure that integer-3 is greater than 0, that printable items on a given print line are 
defined in ascending column-number order and do not overlap, and that each character 
occupies a unique position. 


Space characters are automatically provided for all positions of a print line that are not 
occupied by printable items. 


The first or leftmost character of a print line is column number 1. | 


An entry that, contains a COLUMN NUMBER clause but no LINE NUMBER clause 
must be subordinate to an entry that contains a LINE NUMBER clause. 


An entry that contains a VALUE clause must also have a COLUMN NUMBER clause. 
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GROUP INDICATE Ciause 


The GROUP INDICATE clause causes an associated elementary item to be produced at 
the top of a page or when a control break occurs. 


If a GROUP INDICATE clause is specified, it causes the SOURCE or VALUE clauses to 
be ignored and spaces to be provided except in the following cases: 

e On the first printing of the DETAIL report group in the report 

e On the first printing of the DETAIL report group after a page advance 

e On the first printing of the DETAIL report group after every control break 

If the report-description entry specifies neither a PAGE clause nor a CONTROL clause, 
then a GROUP INDICATE printable item is printed the first time the DETAIL report 


group is printed after the INITIATE statement is executed. Thereafter, spaces are 
supplied for indicated items with SOURCE or VALUE clauses. 


The GROUP INDICATE clause can appear only in a DETAIL report group at the 
elementary item level within an entry that defines a printable item. 


A GROUP INDICATE clause can appear only in a DETAIL report group. 


JUSTIFIED Clause 


The JUSTIFIED clause causes alphanumeric data to be right-justified in a receiving 
field. The rules for using the JUSTIFIED clause in Report Writer are the same as those 
described for the clause in Section 7, “DATA DIVISION.” 


LINE NUMBER Clause 


The LINE NUMBER clause specifies vertical positioning information for its report 
group. A LINE NUMBER clause must be used to establish each print line of a report 


group. 
A LINE-NUMBER clause must not be the only clause specified. 


Refer to the description of the LINE NUMBER clause in Format 1 earlier in this section 
for details about this clause. 


PICTURE Clause 
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The PICTURE clause specifies the output format of an item and is required in Format 3. 
The rules for using the PICTURE clause in Report Writer are the same as those 


described for the clause in Section 6, “Data Concepts” and in Section 7, “DATA 
DIVISION.” 
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SOURCE Clause 


The SOURCE clause specifies the ia item to be printed or designates a data item to be 
summed in a CONTROL FOOTING report group. 


Identifier-1 specifies the sending data item of the implicit MOVE statement that is 
executed to move identifier-1 to the printable item. Identifier-1 must be defined so 
that it conforms to the rules for sending items in the MOVE statement. In a Unisys 
extension, identifier-1 can be any special register, attribute, intrinsic function, or 
identifier. 


The print lines of a report group are formatted immediately before presentation of the 
report group. At that time, the implicit MOVE statements specified by SOURCE clauses 
are executed. 


Identifier-1 can be defined in any section of the DATA DIVISION. If identifier-1 is a 
REPORT SECTION item, it can be only PAGE-COUNTER, LINE-COUNTER, or a sum 
counter of the report in which the SOURCE clause appears. 


SUM Clause 
The SUM clause establishes a sum counter and names the data items to be summed. 


A SUM clause can appear only in a CONTROL FOOTING report group. 
_ Explanation of Sum Clause Format 


identifier-2 and identifier-3 


Identifier-2 and identifier-3 must be defined as numeric data items. When defined in the 
REPORT SECTION, identifier-2 and identifier-3 must be the names of sum counters. 

If the UPON phrase is omitted, any identifiers in the associated SUM clause that are 
themselves sum counters must be defined either in the same report group that contains 
the SUM clause or in a report group at a lower level in the control hierarchy of the 
report. If the UPON phrase is specified, any identifiers in the associated SUM clause 
must not be sum counters. 


UPON 

The UPON phrase selectively subtotals the DETAIL report groups named in the phrase. 
Data-name-2 and data-name-3 must be the names of DETAIL report groups described 
in the same report as the CONTROL FOOTING report group in which the SUM clause 
appears. Data-name-2 and data-name-3 can be qualified by a report-name. 


For more information on the CONTROL FOOTING report group, see “CONTROL 
Clause” earlier in this section. _ 
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RESET ON data-name-4 
Data-name-4 must be one of the data-names specified in the CONTROL clause for this © 
report. Data-name-4 must not be a lower-level control than the associated control for 


the report group in which the RESET phrase appears. 


< For more information on the CONTROL clause, see “CONTROL Clause” earlier in this 
section. 


RESET ON FINAL 


The FINAL option, if specified in the RESET phrase, must also appear in the CONTROL 
clause for the report. 


VALUE Clause 
The VALUE clause defines the value of REPORT SECTION printable items. 
An entry that contains a VALUE clause must also have a COLUMN NUMBER clause. 
Only Format 1 of the VALUE clause is permitted in the REPORT SECTION. 


In a Unisys extension, VA is an abbreviation for VALUE. 


See Also 
For a more detailed description of the VALUE clause, refer to “VALUE Clause” in 
Section 7, “DATA DIVISION.” | 


USAGE Clause (Report Writer) 


A USAGE clause specifies the format of a data item in computer storage. 
The USAGE clause can be used at the elementary item level. The usage of all 


elementary items must be the same as the usage of the file on which the report is 
written. 


See Also 


For a detailed description of the USAGE clause, refer to “USAGE Clause” in Section 7, 
“DATA DIVISION.” j 
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Summary of RD Entries 


Table 12-2 shows all the possible combinations of clauses in Format 3. Each column 
represents an allowable combination of clauses. For example, the first column under 
“Permitted Combinations of Clauses” indicates that when combining the required 
PICTURE and SUM clauses, the LINE clause is allowed but not required. All other 
remaining clauses are invalid for this combination. The PICTURE clause is always 
required. 


Table 12-2. Permissible Clause Combinations in Format 3 Report-Group Description 
Entries 


Clause Permitted Combinations of Clauses 


PICTURE Required Required Required Required Required 


COLUMN Invalid Required Allowed Allowed Required 
SOURCE Invalid | Invalid Required Required Invalid 
SUM Required Required Invalid Invalid Invalid 
VALUE Invalid invalid Invalid Invalid Required 


JUST Invalid Invalid Allowed Invalid Allowed 


BLANK ~ Invalid Allowed Invalid Allowed Invalid 
ZERO 


GROUP Invalid Invalid | Allowed Allowed Allowed 
USAGE Invalid Ailowed Allowed Allowed Allowed 
LINE Allowed Allowed Allowed _ Allowed Allowed 


Understanding Sum Counters 


The SUM clause establishes a sum counter. The sum counter is a numeric data item 
with an operational sign. At run time, each of the values identifier-1, identifier-2, and so 
forth is added directly into the sum counter. This addition is performed under the rules — 
of the ADD statement. . 


The size of the sum counter is equal to the number of receiving character positions 
specified by the PICTURE clause that accompanies the SUM clause in the description of 
the elementary item. 


Only one sum counter exists for an elementary report entry, regardless of the number of 
SUM clauses specified in the elementary report entry. 


If the elementary report entry for a printable item contains a SUM clause, the sum 


counter serves as a source data item. The data contained in the sum counter is moved, 
according to the rules of the MOVE statement, to the printable item for printing. 
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If the data-name appears as the subject of an elementary report entry that contains 
a SUM clause, the data-name is the name of the sum counter, not the name of the 
printable item that the entry can also define. . 


_ The highest permissible qualifier of a sum counter is the report-name. 


PROCEDURE DIVISION statements can alter the contents of sum counters. 


- If two or more identifiers specify the same addend, the addend is added into the sum 


counter as many times as the addend is referenced in the SUM clause. 


Two or more of the data-names can specify the same DETAIL report group. When 
a GENERATE data-name statement for such a DETAIL report group is given, the 
incrementing occurs as many times as data-name appears in the UPON phrase. _ 


In the absence of an explicit RESET phrase, the compiler sets the sum counter to the 
value 0 (zero) when Report Writer processes the CONTROL FOOTING report group 
within which the sum counter is defined. If an explicit RESET phrase is specified, the 
compiler sets the sum counter to 0 (zero) when Report Writer processes the designated 
level of the control hierarchy. The compiler initially sets the sum counter to 0 (zero) 
during execution of the INITIATE statement for the report containing the sum counter. © 


incrementing Sum Counters 
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Report Writer adds the identifiers into the sum counters during execution of the 


‘GENERATE and TERMINATE statements. Report Writer adds each identifier to 


be added into the sum counter at a time that depends on the characteristics of the 
identifier. The characteristics of the identifiers to be added and the time of addition are 
described for each of the following three categories of sum-counter incrementing: 


Category Identifier Characteristics and Time of Addition — 


Subtotaling Subtotaling is the process of accumulating identifiers to be added 
into a sum counter. Subtotaling occurs only during execution of 
GENERATE statements, after Report Writer processes any control 
break, but before it processes the DETAIL report group. 


if the SUM clause contains the UPON phrase, Report Writer 
subtotals the identifiers to be added when it executes a GENERATE 
statement for the designated DETAIL report group. 


If the SUM clause does not contain the UPON phrase, Report Writer 
subtotals the identifiers that are not sum counters when it executes 
any GENERATE data-name statement for the report in which 
the SUM clause appears. 


Rolling Forward Rolling forward is the process of accumulating sum counters defined 
in a lower-level CONTROL FOOTING report group into the sum 
counter. The program rolls forward a sum counter in a lower-level 
CONTROL FOOTING report group when a control break occurs and 

“when the lower-level CONTROL FOOTING report group is processed. 


continued 
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continued 
Category Identifier Characteristics and Time of Addition 
Crossfooting Crossfooting is the process of accumulating a sum counter defined 


in the same CONTROL FOOTING report group into the sum counter. 
Crossfooting occurs when a control break occurs and when the 
~ CONTROL FOOTING report group is processed. 


The program performs the crossfooting according to the sequence in 
which sum counters are defined in the CONTROL FOOTING report 
group; that is, the program completes all crossfooting into the first 
sum counter defined in the CONTROL FOOTING report group. Then 
the program completes all crossfooting into the second sum counter 
defined in the CONTROL FOOTING report group. The program 
repeats this procedure until it completes all the crossfooting 
operations. 


PROCEDURE DIVISION Statements 


The following statements apply in the PROCEDURE DIVISION only with Report 


' Writer: 
e INITIATE 
e GENERATE 


e TERMINATE 
e USE BEFORE REPORTING 


INITIATE Statement 


The INITIATE statement begins processing of a report. 


The general format of this statement is as follows: 


INITIATE report-name-1 [ , report-name-2 ]... 


Explanation of Format 


INITIATE 


The INITIATE statement resets all data-name entries that contain SUM clauses 
associated with the designated report. | 


The INITIATE statement does not open the file with which the report is associated; 
however, the associated file must be open when the INITIATE statement is executed. 
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A second INITIATE statement for a particular report-name cannot be executed unless a 
TERMINATE statement has been executed for that report-name after the execution of 
the first INITIATE statement. 


report-name 


Each report-name must be defined by a report-description (RD) entry in the REPORT 
SECTION of the DATA DIVISION. 


Special Registers 


The PAGE-COUNTER register, if specified, is set to 1 during execution of the 
INITIATE statement. Ifa starting value other than 1 is desired for the associated 
PAGE-COUNTER, the counter can be reset after the INITIATE statement is executed. 


The LINE-COUNTER register, if specified, is set to 0 (zero) before or during execution 
of the INITIATE statement. 


GENERATE Statement 


The GENERATE statement links the PROCEDURE DIVISION to the Report Writer 
at processing time. The Report Writer is described in the REPORT SECTION of the 
DATA DIVISION. 


Data is moved to the data item in the report-group-description entry of the REPORT 
SECTION. This data is edited under the control of the Report Writer according to the 
same rules for movement and editing described for the MOVE statement. 


GENERATE statements for a report can be executed only after an INITIATE statement 
for the report has been executed and before a TERMINATE statement for the report 
has been executed. 


The general format of this statement is as follows: 


GENERATE identifier 
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Explanation of Format 

The identifier represents a DETAIL report group or an RD entry. 

If the identifier represents the name of a DETAIL report group, the GENERATE 
statement performs all automatic operations of the Report Writer and produces an 
output DETAIL report group on the output medium during processing. This type of . 
reporting is called detail reporting. 

If the identifier represents the name of a report-description (RD) entry, the GENERATE 


statement performs all automatic operations of the Report Writer and updates the 
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FOOTING report groups in a particular report description (RD) without producing 

a DETAIL report group associated with the report. In this case, all sum counters 
associated with the report description (RD) are algebraically incremented. This type of 
reporting is called summary reporting. For summary reporting, no more than one TYPE 
DETAIL report group and at least one body group must be present, and the CONTROL 
clause must be specified for the report. 


GENERATE Statement Actions 


A GENERATE statement implicitly produces the following automatic operations (if 
defined) in both detail and summary reporting: 


e Steps and tests the LINE-COUNTER register, the PAGE-COUNTER register, or 
both special registers to produce appropriate PAGE FOOTING, PAGE HEADING, 
or both report groups 


e Recognizes any specified control breaks to produce appropriate CONTROL 
FOOTING report groups, CONTROL HEADING report groups, or both report 


groups 
e Accumulates all specified identifiers into the sum counters, resets the sum counters 


on an associated control break, and performs an updating procedure between 
control-break levels for each set of sum counters 


e Executes any specified routines defined by a USE statement before the generation of 
the associated report groups 


Producing Report Groups 


During execution of the first GENERATE statement, the following report groups 
associated with the report, if specified, are produced in the specified order: 

e REPORT HEADING report group 

e PAGE HEADING report group 

e AllCONTROL HEADING report groups in the following order: final, major, minor 
e DETAIL report group statement 

The following steps occur if the Report Writer recognizes a control break when the 


GENERATE statement is executed. The GENERATE statement cannot be the first 
statement executed for a report. 


1. AllCONTROL FOOTING report groups specified for the report are produced, 
from the minor report group up to.and including the report group specified for the 
identifier that caused the control break. 


2. The CONTROL HEADING report groups specified for the report are produced 
descending order, from the report group specified for the identifier that caused the 
- control break down to the minor report group. 


3. The DETAIL report group specified in the GENERATE statement is produced. 
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TERMINATE Statement 
The TERMINATE statement ends the processing of a report. 


The general format of this statement is as follows: 


TERMINATE report-name-1 [ , report-name-2 ]... 


Explanation of Format 


Each report-name given ina TERMINATE statement must be defined by a 
report-description (RD) entry in the REPORT SECTION of the DATA DIVISION. 


The TERMINATE statement produces all CONTROL FOOTING report groups 
associated with the report as if a control break had just occurred at the highest level, 
and the statement completes the Report Writer functions for the named reports. 
The TERMINATE statement also produces the lasts PAGE FOOTING and REPORT 
FOOTING report groups associated with the report. 


If no GENERATE statements have been executed for a report during the interval 
between the execution of an INITIATE statement and a TERMINATE statement for the 
same report, then associated FOOTING report groups are not produced. 


Appropriate PAGE HEADING report groups, PAGE FOOTING report groups, or both 
report groups are prepared in their respective order for the report group description. 


A second TERMINATE statement for a particular report cannot be executed unless 

a second INITIATE statement has been executed for that report. Ifa TERMINATE 
statement has been executed for a report, a GENERATE statement for that report must 
not be executed unless an intervening INITIATE statement for that report is executed. 


The TERMINATE statement does not close the file associated with the report. You must 
use a CLOSE statement for the file. However, the associated file must be open at the 
time the TERMINATE statement is executed. The TERMINATE statement performs 
Report Writer functions for individually described reports analogous to the I/O functions 
that the CLOSE statement performs for individually described files. 


The SOURCE clauses used in the CONTROL FOOTING FINAL or REPORT FOOTING 


report groups refer to the values of the items during execution of the TERMINATE 
statement. 


USE BEFORE REPORTING Statement 


' This statement specifies PROCEDURE DIVISION statements to be executed 
immediately before Report Writer processes a report group named in the REPORT 
SECTION of the DATA DIVISION. 
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The general format of this statement is as follows: 


USE BEFORE REPORTING identifier-1 


Explanation of Format 


A USE BEFORE REPORTING statement, when present, must immediately follow 
section header in the DECLARATIVES SECTION of the PROCEDURE DIVISION and 
must be followed by a period followed by a space. The remainder of the section must 
consist of one or more procedural paragraphs defining the procedures to be used. | 


Identifier-1 represents a report group named in the REPORT SECTION of the DATA 
DIVISION. An identifier must not appear in more than one USE statement. 


No Report Writer statement (GENERATE, INITIATE, or TERMINATE) can be 
written in a procedural paragraph or paragraphs following the USE statement in the 
DECLARATIVES SECTION. 


The USE statement itself is never executed; rather, it defines the conditions that call for 
execution of the USE procedures. 


Report Writer executes the designated procedures immediately before it produces the 
named report group, regardless of control-break associations with report groups. 


A USE BEFORE REPORTING statement must not alter the value of any control data 
item. ; 


Report Writer Program Example 


The sample program in Example 12-1 uses the Report Writer program to produce the 
report shown in Figure 12-3. The data file input to the program is shown in Figure 12-2. 


Comment-entry lines in the program indicate the portions of code that describe the 
- various report group types. The corresponding output is shown with numbers on the far 
right that indicate the report group type that caused the line to be printed. 


G20208 IDENTIFICATION DIVISION. 

@2G30G PROGRAM-ID. FED-SCHOOL-SYSTEM. 

208408 AUTHOR. BERKOWITZ. 

@@858@ ENVIRONMENT DIVISION. 

Q9B6GG@ INPUT-OUTPUT SECTION. 

098708 FILE-CONTROL. 

BOOB SELECT PENNI ASSIGN TO SORT DISK. 
BBBIGB SELECT INFILE ASSIGN TO DISK. 
0010808 SELECT REPORTFILE ASSIGN TO PRINTER. 
861198 DATA DIVISION. 

681200 FILE SECTION. 


Example 12-1. Sample Report Writer Program 
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@01380 FD INFILE BLOCK CONTAINS 3@ RECORDS. 


@@1358 @1 IN-REC PICTURE X(84). 

@@14@0 SD PENNI. @1 FROMM. 

Q01508 2 FILLER PICTURE XX. 

QQ1600 G2 STUDENT. 

2017202 @3 NAME-L PICTURE X(39). 

201828 @3 NAME-F — PICTURE X(10). 

QG1900 2 FILLER PICTURE XX. 

Q22000 02 GRADE PICTURE 99. 

922100 2 FILLER PICTURE XX. 

@22206 B82 ROOM PICTURE 999. 

@02300 2 FILLER. PICTURE 99. 

@02400 62 MONTHH PICTURE 99. 

Q02500 82 DAYY PICTURE 99. 

@02608 2 YR PICTURE 99. 

@02700 2 FILLER PICTURE X(2). 

Q82808 2 TAL PICTURE 9. 

Q02850 2 FILLER PICTURE X(22). 

@82900 FD REPORTFILE = REPORT IS ABS-REPORT. 

Q@3008 WORKING-STORAGE SECTION. 

9@3188 77 SAVED-MONTH PICTURE 99 VALUE IS @. 

@03208 77 CONTINUED PICTURE X(11) VALUE IS SPACE. 
003308 77 ABSS PIC X(8) VALUE "ABSENCES". 

@03408 77 CA PIC X(19) VALUE "CUMULATIVE ABSENCES". 
@@350@8 77 TAL-CTR BINARY PIC 9999. | 

@23620 77 MTHIX PICTURE 99. 

003708 @1 HEAD-1. | 

Q03828 @2 FILLER PIC X(22) VALUE SPACES. 

G039008 @2 HEAD-LINE PIC X(74) VALUE "MONTH DAY 
Q24000- "GRADE ROOM NAME ". 
904100 @2 FILLER PIC X(36) VALUE SPACES. 

@24200 @1 MONTH-TABLE. 

904300 @2 MONTH-1. 

004408 ®3 FILLER PICTURE A(9) VALUE IS "JANUARY ". 
004500 @3 FILLER PICTURE A(9) VALUE IS "FEBRUARY ". 
204600 @3 FILLER PICTURE A(9) VALUE IS "MARCH ". 
224700 @3 FILLER PICTURE A(9) VALUE IS "APRIL". 
204820 @3 FILLER PICTURE A(9) VALUE IS "MAY u, 
224900 @3 FILLER PICTURE A(9) VALUE IS "JUNE i 
Q25000 @3 FILLER PICTURE A(9) VALUE IS "JULY a, 
2051908 @3 FILLER PICTURE A(9) VALUE IS "AUGUST ". 
225200 @3 FILLER PICTURE A(9) VALUE IS "SEPTEMBER". 
225320 @3 FILLER PICTURE A(9) VALUE IS "OCTOBER ". 
225400 @3 FILLER PICTURE A(9) VALUE IS "NOVEMBER ". 
225500 @3 FILLER PICTURE A(9) VALUE IS "DECEMBER ". 
225600 @3 FILLER PICTURE A(9) VALUE SPACES. 

205700 @2 MONTH-2 REDEFINES MONTH-1. 

225802 @3 MONTHNAME PICTURE A(9) OCCURS 13 TIMES. 
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095998 REPORT SECTION. 
9960988 RD ABS-REPORT CONTROLS ARE FINAL, MONTHH, DAYY, GRADE 
966180 PAGE LIMIT IS 56 LINES HEADING 2 
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BQ6206 
8862 19* 
8B6220* 
086230* 
BB6240* 


Report Writer 


FIRST DETAIL 19 LAST DETAIL 45 FOOTING 55. 


The following lines produce the report heading. 
See <--1 in sample Report Writer report. 


826306 G1 TYPE IS REPORT HEADING. 


BB6400 
086580 
GG6510* 
026520* 
G26530* 
086540* 


@2 LINE NUMBER IS 2 COLUMN 57 -PIC X(17) 
VALUE "FED SCHOOL SYSTEM". 


The following lines produce the page heading. 
See <--2 in sample Report Writer report. 


@@6696 01 PAGE-HEAD TYPE IS PAGE HEADING. 


006780 
BB6880 
BB698B 
887008 
007196 
987280 
987300 
B27 406 
027500 
GB751* 
G87 520* 
8B7530* 
807 540* 


@2 LINE NUMBER IS 3 COLUMN 52 PIC X(26) 
VALUE "STUDENT ABSENTEEISM REPORT". 
@2 LINE NUMBER IS 6. 
@3 COLUMN IS 56 PIC X(9) 
SOURCE IS MONTHNAME OF MONTH-2(MONTHH) . 


@3 COLUMN IS 66 PIC X(8) SOURCE IS ABSS. 
93 COLUMN IS 76 PIC X(11) SOURCE IS CONTINUED. 
O2 LINE IS 8. 


83 COLUMN IS 1 PIC X(132) | SOURCE HEAD-1. 


The following lines produce the detail lines. 
See <--3 in sample Report Writer report. 


927608 @1 DETAIL-LINE TYPE IS DETAIL LINE NUMBER IS PLUS 1. 


907700 
907890 
907900 
‘908000 
908120 
928200 
908320 
908499 
— 908419* 
g28429* 
G98430* 
B08449* 


@2 COLUMN IS 24 GROUP INDICATE PIC X(9) 

SOURCE IS MONTHNAME OF MONTH-2(MONTHH) . 
@2 COLUMN IS 41 GROUP INDICATE PICTURE IS 99 

SOURCE IS DAYY. | 
@2 COLUMN IS 54 GROUP INDICATE PIC 99 SOURCE IS GRADE. 
@2 COLUMN IS 67 PIC 999 SOURCE IS ROOM. . 
@2 COLUMN IS 8@ PIC X(2@) SOURCE IS NAME-L. 
@2 COLUMN IS 181 PIC X(1@) SOURCE IS NAME-F. 


The following lines produce the grade control footing. 
See <--4 in sample Report Writer report. 


088508 G1 TYPE IS CONTROL FOOTING GRADE. 


GB8609 
088780 
9887 10* 
98872B* 
968730* 
9687 40* 


@2 -LINE NUMBER IS PLUS 2. . 
@3 COLUMN 1 PIC X(132) VALUE SPACE. 


The following lines produce the day control footing. 
See <--5 in sample Report Writer report. 


908808 O91 TESTER TYPE IS CONTROL FOOTING DAYY. 


988908 
GB9BBB 
989180 
889286 
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@2 LINE NUMBER IS PLUS 2. 
@3 COLUMN 2 PIC X(12) VA "ABSENCES FOR". 
@3 COLUMN 24 PICTURE Z9 SOURCE SAVED-MONTH. 
@3 COLUMN 26 PICTURE X VALUE --. 
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869300 — @3 COLUMN 27 PICTURE 99 SOURCE DAYY. : 

809400 83 NO-ABS COLUMN 49 PIC 999 SUM TAL. 
869500 @3 COLUMN 65 PIC X(19) SOURCE CA. 

GB9600 @3 COLUMN 85 PIC 999 SUM TAL RESET ON FINAL. 

909798 92 LINE PLUS 1 COLUMN 1 ~~ PIC X(132) VA ALL *. 


999720* The following lines produce the month control footing. 
989730* See <--6 in sample Report Writer report. 


9B974B* 

G69806 91 TYPE CONTROL FOOTING MONTHH 

BB999B LINE PLUS 2 NEXT GROUP NEXT PAGE. 

818800 @2 COLUMN 16 PIC X(28) VALUE "TOTAL NUMBER OF ABSENCES FOR". 
818180 @2 COLUMN IS 46 PIC X(9) 

G198200 SOURCE MONTHNAME OF MONTH-2(SAVED-MONTH) . 

819300 @2 COLUMN 57 PIC XXX VALUE "WAS". 

818400 82 TOT COLUMN 61 PIC 999 SUM NO-ABS. 

818410* 


G18420* The following lines produce the page heading. 
919438* See <--7 in sample Report Writer report. 


G18449* 

Q1850@ @1 TYPE PAGE FOOTING LINE PLUS 1. 

018680 @2 COLUMN 59. PICTURE X(12) VALUE "REPORT-PAGE-". 
918788 @2 COLUMN 71 PICTURE 99 SOURCE PAGE-COUNTER. 
0187 10* 


@1872@* The following lines produce the report footing. 
918738* See <--8 in sample Report Writer report. 


@18748* 

818806 91 TYPE REPORT FOOTING. 

019998 - M2 LINE PLUS 1 COLUMN 32 PICTURE A(13) 
911088 VALUE "END OF REPORT". 


G1110@ PROCEDURE DIVISION. 

811200 DECLARATIVES. 

811308 PAGE-HEAD-RTN SECTION. 

811488 USE BEFORE REPORTING PAGE-HEAD. 
811508 TEST-CONT. 

911609 IF MONTHH = SAVED-MONTH MOVE "(CONTINUED)" TO CONTINUED 
911798 ELSE MOVE SPACES TO CONTINUED 
911898 MOVE MONTHH TO SAVED-MONTH. 
811988 END DECLARATIVES. 

@12006 SORTING SECTION. 

812199 SORTER. 

812286 SORT PENNI ON ASCENDING KEY 

G12308 MONTHH, DAYY, GRADE, ROOM, STUDENT 
912329 USING INFILE OUTPUT PROCEDURE IS REPORTER. 
912330 DISPLAY MONTHH. 

G12348 MOVE MONTHH TO MTHIX. 

812506 END-OF-THE-SORT. STOP RUN. 

812600 REPORTER SECTION. 

812780 INITIATE-REPORT. 

812988 OPEN OUTPUT REPORTFILE. 

913000 INITIATE ABS-REPORT. 

913198 UNWIND-THE~SORT. 
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813206 
813386 
813498 
0134668 


RETURN PENNI RECORD AT END 
TERMINATE ABS-REPORT STOP RUN. 


GENERATE DETAIL-LINE GO TO UNWIND-THE-SORT. 


STOP RUN. 


Example 12—1. Sample Report Writer Program (cont.) 
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Figure 12-2 shows the input data file INFILE) that produces the output shown in 


Figure 12-3. 


CODDINGTO 
MILLSTEIN 
BURKLAND 
MCCOY 
LUBASCH 
JOFFEE 
EAGLE 
DANIELSON 
HUBERT 
WONG 
CODDINGTO 
CARROLL 
HANSON 
AUSTIN 


N KIMBERLY 
SANDRA 
JOSEPH 
JUDY 
DANIEL 
JOHN 
MIKE 
FRED 
THOMAS 
SUSIE 

N DARIN 
JENNIFER 
KAREN 
EUGENE 


Q3 
93 
Q3 
G1 
01 
G1 
85 
B5 
93 
93 
G2 
G2 
G2 
G2 


125 
121 
121 
142 
142 
142 
153 
153 
115 
111 
193 
192 
192 
191 


891288 
891288 
991288 
891888 
891988 
891888 
898788 
898788 
896788 
998788 
698788 
898788 
8986788 
898788 


[a ee oe Se ee ee ee 


Figure 12-2. Input Data File to Sample Report Writer Program 


Figure 12-3 shows output from the sample Report Writer program. The numbers on the 
far right side (for example, <—1) indicate the report group type that caused the line to _ 
be printed. These numbers shown on the output correspond to the numbers shown in 
the comment-entry lines of the program. 
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FED SCHOOL SYSTEM > veken dT 
STUDENT ABSENTEEISM REPORT <-- 2 

SEPTEMBER ABSENCES $6-:2 

MONTH DAY GRADE — ROOM NAME OR 
SEPTEMBER 87 22 161 AUSTIN EUGENE <-- 3 
102 CARROLL JENNIFER <-- 3 

192 HANSON | KAREN ane°3 

183 CODDINGTON DARIN <-- 3 

Swed 

SEPTEMBER 97 83 111 WONG | SUSIE ana, 5 
115 HUBERT THOMAS = <-- 3 


SEPTEMBER @7 @5 153 DANIELSON FRED <-- 
, 153 EAGLE ed MIKE <ue 


ABSENCES FOR 9-97 828 CUMULATIVE ABSENCES 698 <-- 


eee ee ee eee ee ee ee ee eee eS eS ee 
SEPTEMBER 19 G1 142 JOFFEE JOHN <-- 
142 LUBASCH DANTEL <-- 


142 ~~. MCCOY JUDY <-- 


ABSENCES FOR 9-19 883 CUMULATIVE ABSENCES 911 <-- 
KKK KKK IK KK KKK KKK IKKE IKK ARIK KIKI IIE ARIK ER ERIKA EIR ERR 
- SEPTEMBER 12 03 121 BURKLAND JOSEPH <-- 
121 MILLSTEIN SANDRA <-~ 

125 CODDINGTON - KIMBERLY <-- 


ABSENCES FOR 9-12 983 CUMULATIVE ABSENCES 814 <-- 


KEKKKEKEKKKKKKEKEKEREKKEKEKEREREREREREKRERREERKEKEKRRKEEREEKKREREREERE Cn 


A 

( 

’ 
DAADAaAANMPWWWaAanbPwWwWonanPhP WW PP 


TOTAL NUMBER OF ABSENCES FOR SEPTEMBER WAS 914 <-- 


REPORT-PAGE-91 <-- 7 
END OF REPORT <-- 8 


Figure 12-3. Sample Report Writer Report 
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section 13 
ANSI Inter-Program Communication 
(IPC) 


The Inter-Program Communication (IPC) module provides a way for a program to 
communicate with one or more other programs. This communication is defined as 
e The ability to transfer control from one program to another within a run unit 

e The ability of both programs to have access to the same data items 

The ANSI-74 IPC module is a subset of libraries, which are described in Section 15, 
“Libraries.” The IPC implementation requires that a called program adhere to the 
following rules: 

e The SHARING compiler control option has the value SHAREDBYRUNUNIT. 
e The program does not return a value. 


e The program has a single entry point, named PROCEDUREDIVISION. 


See Also 


Deviations from these rules are Unisys extensions, which are described in Section 15, 
“Libraries.” 


LINKAGE SECTION in the IPC Module 


You must code a LINKAGE SECTION in the DATA DIVISION when you are using IPC. 


The LINKAGE SECTION appears in a called program. It describes data that is available 
through the calling program but that is accessed in both the calling and the called 
programs. 


. No space is allocated in the called program for data items referred to by data-names 
in the LINKAGE SECTION of that program. PROCEDURE DIVISION references 
to these data items are resolved at run time by equating the reference i in the called 
program to the location used in the calling program. 


In the case of index-names, no such correspondence is established. Index-names in the 
called and calling programs always refer to separate indexes. 


The LINKAGE SECTION in a program is meaningful only if the object program 


functions under the control of a CALL statement and if the CALL statement in the 
calling program contains a USING phrase. 
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Data items defined in the LINKAGE SECTION of the called program can be accessed 
within the PROCEDURE DIVISION of the called program only if they are specified as 
operands of the USING phrase of the PROCEDURE DIVISION header or if they are 
subordinate to such operands and the object program is under the control of a CALL 
statement that specifies a USING phrase. 


The structure of the LINKAGE SECTION is the same as that previously described for 
the WORKING-STORAGE SECTION, beginning with a section header and followed by 
data-description entries for noncontiguous data items, record-description entries, or 
both. 


Each LINKAGE SECTION record-name and noncontiguous item name must be unique 
within the called program because it cannot be qualified. Data items defined in the 
LINKAGE SECTION of the called program must not be associated with data items 
defined in the REPORT SECTION of the calling program. 


‘Of those items defined in the LINKAGE SECTION, the only items that can be referred 


to in the PROCEDURE DIVISION are the following: 


e Data-name-1, data-name-2, and so on, in the USING phrase of the PROCEDURE 
DIVISION header 

e Data items subordinate to these data-names 

e Condition-names, index-names, or both associated with data-names, subordinate 
data items, or both 


In both calling and called programs, the following rules apply to data items used ae the 
operating system as parameters for parameter-matching: 


e 01-level items of DISPLAY, COME or INDEX usages, and 77-level items with 
USAGE IS DISPLAY are treated as EBCDIC arrays. 


e 77-level COMP or INDEX items are treated as hex arrays. 


See Also 


Refer to Section 15, “Libraries,” for information on designating data items of other 


usages as parameters. 


Noncontiguous Linkage Storage 
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Items in the LINKAGE SECTION that have no hierarchic adiohoaalis to one another 
need not be grouped into records. Instead, these items are classified and defined as 
noncontiguous elementary items. Each item is defined in a separate data-description 
entry that begins with the special level-number 77. 
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The following data clauses are required in each data-description entry: 
e Level-number 77 

e _ DATA-NAME 

e PICTURE clause or USAGE IS INDEX clause 


Other ‘elavacsaisaed clauses are optional and ¢ can be used to complete the description 
of the item, if necessary. 


Linkage Records 


Data elements in the LINKAGE SECTION that have a definite hierarchic relationship to 
one another must be grouped into records according to the rules for formation of record 
descriptions. Any clause used in an input or an output record description can be used in 


a LINKAGE SECTION. 
- Usages other than DISPLAY, COMP or INDEX are Unisys extensions and their use 
as parameters is described in Section 15, “Libraries.” The WITH LOWER-BOUNDS 
clause, also a Unisys extension, is ignored for parameter-linking purposes in all IPC and 
~ library interfaces. 


The VALUE clause must not be specified in the LINKAGE SECTION except in 
condition-name entries (88-level). 


PROCEDURE DIVISION in the IPC Module 


The following constructs apply to the PROCEDURE DIVISION when IPC is used. 


PROCEDURE DIVISION Header 


The PROCEDURE DIVISION is identified by, and must begin with, the following 
header: 


PROCEDURE DIVISION [ USING {data-name} ...] . 


- The USING phrase is present if the object program is to function under the control of 
a CALL statement and the CALL statement in the calling program contains a USING 
phrase. Each operand in the USING phrase of the PROCEDURE DIVISION header 
must be defined as a data item in the LINKAGE SECTION of the program in which this 
header occurs, and each operand must have a level-number of 01 or 77. 


Within a called program, LINKAGE SECTION data items are processed according to the 
data descriptions given in the called program. 
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Inter-Program Communication (IPC) implementation is not allowed if a data item is 
declared RECEIVED BY CONTENT. The RECEIVED BY CONTENT declaration on a 
parameter is supported only for tasking and bound procedures. 


CALL Statement 


The execution of a CALL statement causes control to pass from a calling program to 
acalled program. The calling program is the program in which the CALL statement 
appears. The called program is the program specified by the value of the identifier or the 
literal in the CALL statement. 


The general format of this statement is as follows: 


CALL 


{ identifier-1 


literal-1 \ | USING data-name-1 [, data-name-2]...] 
eral- 


[; ON OVERFLOW imperative-statement | 


Note: The following format instructions and general rules assume that the 
program being called is a COBOL74 program with the value of the 
SHARING compiler control option equal to SHAREDBYRUNUNIT 
(the default). This restriction is required for adherence to. ANSI-74 
COBOL Inter-Program Communication (IPC) conventions. For the 
effects of a CALL verb on programs that do not meet the preceding 
criteria, see Section 15, “Libraries.” . 


Explanation of Format 
The literal must be a nonnumeric literal. 


The identifier must be defined as an alphanumeric data item whose value can be a 
program-name. : 


The USING option is included in the CALL statement only if a USING phrase is present 
in the PROCEDURE DIVISION header of the called program. The number of operands 
in each USING phrase must be identical. 


The data-names indicate the data items available to a calling program that can be 
accessed in the called program. A data-name must be defined as a data item in the 
FILE, WORKING-STORAGE, COMMUNICATION, or LINKAGE SECTION; must 
have a level-number of 01 or 77; and must not redefine another data item. The 
data-name can be qualified when it refers to a data item defined in the FILE SECTION 
or COMMUNICATION SECTION. . 


The order of appearance of the data-names in the USING phrase of the CALL 
statement and the USING phrase in the PROCEDURE DIVISION header is critical. 
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Corresponding data-names refer to a single set of data available to the called and calling 
programs. The correspondence is by position, not by name. In index-names, no such 
correspondence is established; index-names in the called and calling programs always 
refer to separate indexes. 


A parameter in a USING clause cannot redefine another item either implicitly in the 
FILE SECTION or explicitly with a REDEFINES clause. Also, 77-level items that have 
been redefined can yield unexpected results. For example, referring to a 77-level item in 
a REDEFINES clause can cause it to be treated as if it had been declared asa 0l-level - 
item. 


The ON OVERFLOW option performs the imperative-statement if a syntax error occurs. 


General Rules 


A called program is in the initial state the first time it is called within a run unit and the 
first time it is called after a CANCEL statement is sent to the called program. 


Called programs can contain CALL statements. However, a called program must not 
contain a CALL statement that directly or indirectly calls the calling program. 


If you are using the Segmentation module, the CALL statement can appear anywhere 
within a segmented program. The implementor must provide all controls necessary to 
ensure that the proper logic flow is maintained. Therefore, when a CALL statement 
appears in a section with a segment-number greater than or equal to 50, that segment 
is in the last-used state when the EXIT PROGRAM statement returns control to the 
calling program. 


CANCEL Statement 


The CANCEL statement releases the memory areas occupied by the called program. 


The general format of this statement is as follows: 


CANCEL { 


identifier-1 } { identifier-2 } 
literal-1 ’ | literal-2 _ 


Explanation of Format 
The literal must be a nonnumeric literal. 


The identifier must be an alphanumeric data item. 
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General Rules 


Note: The following rules assume that the program being called is a 
COBOL74 program with the value of the SHARING compiler control 
option equal to SHAREDBYRUNUNIT (the default). This restriction 
is required for adherence to ANSI-74 COBOL Inter-Program 
Communication (IPC) conventions. For the effects of a CANCEL verb 
on programs that do not meet the preceding criteria, see Section 15, 
“Libraries.” 


After execution of a CANCEL statement, the called program ceases to have any logical 
relationship to the run unit in which the CANCEL statement appears. A CALL 
statement naming the same program that is subsequently executed results in initiation 
of that program in its initial state. The memory areas associated with the named 
program are released so as to be made available for disposition by the operating system. 


A program named in the CANCEL statement must not refer to any program that has 
been called and has not yet executed an EXIT PROGRAM statement. 


A logical relationship to a canceled program is established only by execution of a 
subsequent CALL statement. 


A called program is canceled if it is used as the operand of a CANCEL statement or if the 
run unit of which the program is a member is terminated. 


No action is taken when an executed CANCEL statement names a program that has not 
been called in this run unit or that has been called and is canceled. Control passes to the 
next statement. 


EXIT PROGRAM Statement 


The EXIT PROGRAM statement marks the logical end of a called program. 


The general format of this statement is as follows: 


EXIT PROGRAM . 
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Explanation of Format 


The EXIT PROGRAM statement must appear in a sentence by itself. The EXIT 
PROGRAM sentence must appear in a paragraph by itself. 


An execution of an EXIT PROGRAM statement in a called program causes control to 
be passed to the calling program. Execution of an EXIT PROGRAM statement in a 
program that is not called causes the program to act as if the statement were an EXIT 
statement. _ 
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See Also 


For more information on the EXIT statement, refer to “EXIT” in Section 9, 
“PROCEDURE DIVISION Statements.” 


STOP RUN Statement 


The STOP RUN statement permanently ends the called program and all other programs 
in the run unit. . 


The STOP literal statement in a called program has no effect and should not be used. 


See Also 


_ For more information on the STOP statement, refer to “STOP” in Section 9, 
“PROCEDURE DIVISION Statements.” 
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Section 14 
COMMUNICATION SECTION 


The communication module provides the ability to access, process, and create messages 
or portions thereof. The module also gives you the capability to communicate through a 
message control system (MCS) with local and remote communication devices. 


Note: The ANSI-74 MCS concept differs from the Unisys MCS concept. 

Messages are communicated in a device-independent symbolic manner. Specific 

devices and system structures are known to the COBOL74 user only symbolically. This 
generality between the compiled program and the particular system is achieved by 

an interface called data communications interface (DCI). The general abilities of the 
compiler are adapted to the specific device needs of an application through a DCI library. 


For information on using COMS headers, refer to Volume 2 of this manual. 


DCILIBRARY Library 


A DCI library is a library to which the compiler builds references whenever a program 
uses the ACCEPT, DISABLE, ENABLE, RECEIVE, or SEND statements; in fact, a DCI 
library must be present for a COBOL program to use these verbs. 


A DCI library allows programs to deal with symbolic sources and destinations instead of 


the actual peripherals and thus avoid recompilation when the actual peripherals are 
changed or rearranged. 


DCIENTRYPOINT 


The library reference is built with the title DCILIBRARY and the entry-point name 
DCIENTRYPOINT. This entry point is an untyped procedure with the em parameters 
described on the following pages. 


Parameter 1 of DCIENTRYPOINT 


Parameter 1 is an integer with a value indicating which one of the following 11 functions 


to perform: 
Value Function to Perform 
‘dl ACCEPT MESSAGE COUNT 
2 | DISABLE 
3 ENABLE 
4 


_ RECEIVE 


- continued 
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continued 
‘Value Function to Perform 
5 SEND 
6 ~ BEGIN TRANSACTION WITH TEXT (Unisys extension) 
7 BEGIN TRANSACTION ABORT (Unisys extension) 
8 MID TRANSACTION (Unisys extension) 
9 END TRANSACTION ABORT (Unisys extension) 
10 END TRANSACTION WITH NO TEXT (Unisys extension) 
11 END TRANSACTION WITH TEXT (Unisys extension) 


Refer to Volume 2 for additional information about parameters 6 through 11. 


Parameter 2 of DCIENTRYPOINT 


Parameter 2 is an EBCDIC array (unindexed descriptor) of the COBOL program 
communication description (CD). This parameter must have one of the following two 
formats. Format 1 is used with all input functions, and Format 2 is used with all output - 
functions. ; 


Format 1: (ACCEPT, DISABLE input, ENABLE input, or RECEIVE) 


@1 CD-ARRAY. . : 
@2 QUEUE-NAME PIC X(12). 
$2 SUB-QUEUE-1-NAME PIC X(12). 
@2 SUB-QUEUE-2-NAME _ PIC X(12). 
@2 SUB-QUEUE~3-NAME PIC X(12). 
@2 MESSAGE-DATE PIC 9(6). 
@2 MESSAGE-TIME PIC 9(8). 
@2 SOURCE-NAME PIC X(12). 
G2 TEXT-LENGTH 3 PIC 9(4). 
- @2 END-KEY PIC X. 
@2 STATUS-KEY PIC XX. 
G2 


MESSAGE-COUNT PIC 9(6). 


Format 2: (DISABLE output, ENABLE output, or SEND) 


@1 CD-ARRAY. 
@2 DESTINATION-COUNT PIC 9(4). 
@2 TEXT-LENGTH PIC 9(4). 
@2 STATUS-KEY PIC XX. 
@2 DESTINATION-TABLE OCCURS <nnnn> TIMES. 
@3 ERROR-KEY - PIC X. 
@3 DESTINATION-NAME PIC X(12). 
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Parameter 3 of DCIENTRYPOINT 


Parameter 3 is an integer specifying the size of the destination array within the ANSI 
CD. This integer is meaningful only for the SEND verb and should be ignored by the 
custom-written DCILIBRARY for all other verbs. 


Note: Refer to Volume 2 for information about the procedure that links 
COMS to its own DCI library. 


Parameter 4 of DCIENTRYPOINT 


Parameter 4 is an EBCDIC ARRAY (unindexed descriptor) containing either the 
messages (if the function is a SEND statement or a RECEIVE statement) or the 
password (if the function is an ENABLE statement or a DISABLE statement. 


Parameter 5 of DCIENTRYPOINT 


Parameter 5 is an integer with a value indicating the length, in characters, of the array 
(in parameter 5) that contains the messages or the password. This value is distinct from 
the length of the information contained in this array, which you maintain in the CD 
TEXT-LENGTH field of the array in parameter 2. 


Parameter 6 of DCIENTRYPOINT 


Parameter 6 is an integer with a value indicating either the type of end indicator to be 
sent or received, or the type of enable or disable operation to be performed. For a SEND 
statement or a RECEIVE statement, the value specifies the end indicator as follows: 


Value End Indicator 

1 ES! (end of segment/receive segment) 

2 EMI (end of message/receive message) 

3 EGI (end of group) 
For a DISABLE statement or an ENABLE statement, the value specifies the device type 
as follows: 

Value Device Type 

11 Input terminal 

12 Input 

13 Output 


Parameter 7 of DCIENTRYPOINT 


Parameter 7 is an integer with a value that indicates advancing control when the 
function being performed is a SEND statement, and indicates whether or not to wait for 
messages when the function is a RECEIVE statement. 
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For a SEND statement , the value specifies advancing as follows: - 


Value Type of Advancing 
QO. No advancing 

1 After lines 

2 Before lines 

3 After page 

4 Before page 


For a RECEIVE statement, the value of the integer can be set in the COBOL program or 
by the DCI library. 


When set in the program, the value indicates to the DCI library whether or not to wait 
if no message or text is available. A value of 0 (zero) means do not wait, and a value 
greater than 0 means wait that number of seconds. If this parameter is set to 0 anda 
NO DATA clause is supplied, no waiting occurs and the action specified in the NO DATA 
clause is taken if no message is available. 


The DCI library, before returning control to the program, sets the value of the integer to 
1 if no text is available; otherwise, a value of 0 is returned with the text to the program. 


Parameter 8 of DCIENTRYPOINT 


Parameter 8 is an integer that equals the amount to advance ina SEND function. Ifa 
SEND function is not being performed, this parameter’s value is 0. 


Program Sample: CD Array 
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The second parameter, the CD array, allows communication between the COBOL 
program and the DCI library. The COBOL program maintains the CD array passed by 
the compiler. The DCI library updates information in the CD array it receives. 


The information in the CD should be updated in coordination with the COBOL74 
program according to the rules for updating items in the CD array. These updating 
operations include setting the values of the status key, collecting messages, handling 
queues, and checking password validity. 


The DCI library can be written in COBOL74, ALGOL, or DCALGOL and allows access 
to disk files, remote files, or port files. The symbolic queues, selection algorithms, and 
sources and destinations as established in the ANSI-74 COBOL standard can be tailored 
to the particular application by using the DCI library. 


Example 14-1 shows a typical DCI library entry pow written in COBOL that declares 
eight parameters. 
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(1) 
(2) 


(3) 
(4) 


(5) 
(6) 
(7) 
(8) 
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IDENTIFICATION DIVISION. 
PROGRAM-ID. DCIENTRYPOINT. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
LINKAGE SECTION. 
77 DCI-FUNCTION 
81 THE-CD 
81 INPUT-CD 
82 SYMBOLIC-QUEUE 
G2 SYMBOLIC-SUB-QUEUE-1 
82 SYMBOLIC-SUB-QUEUE-2 
@2 SYMBOLIC-SUB-QUEUE-3 
@2 MESSAGE-DATE 
@2 MESSAGE-TIME 
82 SYMBOLIC-SOURCE 
@2 TEXT-LENGTH 
@2 END-KEY 
®2 STATUS-KEY 
B2 MESSAGE-COUNT 
G1 OUTPUT-CD 
G2 DESTINATION-COUNT 
@2 TEXT-LENGTH 
@2 STATUS-KEY 
62 DESTINATION-TABLE 


@3 ERROR-KEY - 
@3 SYMBOLIC-DESTINATION 
77 THE-CD-OCCURRENCES 
1 THE-MESSAGE 
@3 THE-MESSAGE-SUB 


77 THE-MESSAGE-LENGTH 

77 I10-OR-END-INDICATOR 

77 NO-DATA-OR-ADVANCING-TYPE 
77 ADVANCING-VALUE 


PROCEDURE DIVISION 
USING DCI-FUNCTION, 
THE-CD, 
THE-CD-OCCURRENCES, 
THE-MESSAGE, 
THE-MESSAGE-LENGTH, 
10-OR-END-INDICATOR, 


COMMUNICATION SECTION 


COMP PIC 9. 
PIC X(244). 
REDEFINES THE-CD. 
PIC X(12). 
PIC X(12). 
PIC X(12). 
PIC X(12). 
PIC 9(6). 
PIC 9(8). 
PIC X(12). 
PIC 9(4). 
PIC X. 
PIC XX. 
PIC 9(6). 
REDEFINES THE-CD. 
PIC 9(4). 
PIC 9(4). 
PIC XX. 
OCCURS 1 TO 18 DEPENDING 
ON THE-CD-OCCURRENCES. 
PIC X. 
PIC X(12). 
COMP PIC 999. 


PIC X 
OCCURS 1 TO 9999 DEPENDING 
ON THE-MESSAGE-LENGTH. 
COMP PIC 999. 
COMP PIC 99. 
COMP PIC 99. 
COMP PIC 99. 


NO-DATA-OR-ADVANCING-TYPE, 


_ ADVANCING-VALUE. 
MAIN SECTION. 
Pi. 


PERFORM FUNCTION-SPECIFIED-BY-DCI-FUNCTION. 


EXIT PROGRAM. 


Example 14-1. Example Program for DCI Library Entry Point 


14-5 


COMMUNICATION SECTION 


DATA DIVISION in the Communication Module 
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You must code a COMMUNICATION SECTION in the the DATA DIVISION when .you 
use the communication module. 


In a COBOL program, the communication-description (CD) entries represent the highest 
level of organization in the COMMUNICATION SECTION. The COMMUNICATION 
SECTION header is followed by a communication-description (CD) entry consisting of a 
level indicator, a data-name, and a series of independent clauses. These clauses indicate 
the queues and subqueues, the message date and time, the source, the text length, 

the status and end keys, and message count for input. These clauses also specify the 
destination count, the text length, the status and error keys, and destinations for output. 
The entry itself is terminated by a period. These record areas can be implicitly redefined 
by user-specified, record-description entries following the various communication- 
description clauses. 
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The general formats of this entry are described on the following pages. 


CD Format 1 


CD cd-name FOR [ INITIAL ] INPUT — 

[; SYMBOLIC QUEUE IS data-name-1 | 

[ ; SYMBOLIC SUB-QUEUE-1 IS data-name-2 ] 
[ ; SYMBOLIC SUB-QUEUE-2 IS data-name-8 | 
[ ; SYMBOLIC SUB-QUEUE-3 IS data-name-4 ] 
| ;| MESSAGE DATE IS data-name-5 | 

[ ; MESSAGE TIME IS data-name-6 | 

[ ; SYMBOLIC SOURCE IS data-name-7 | 

[ ; TEXT LENGTH IS data-name-8 | 

{; END KEY IS data-name-9 ] 

[ ; STATUS KEY data-name-10 | 

[; MESSAGE COUNT IS Pere ] 


EB CONVERSATION ARBA IS data-name-12 SIZE IS literal-1 | 


[ data-name-1, data-name-2, ..., data-name-11 ] 
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Explanation of CD Format 1 
ACD entry must appear only in the COMMUNICATION SECTION. 


If none of the optional clauses are specified, a 01-level data-description entry must follow | 
the CD entry. 


For each standard input CD, a record area of 87 characters is allocated. 


Use of the 01-level data-description entry or the optional clauses results in a record with 
an implicit description that is equivalent to the following description: 


implicit Description Comment 


Q1 data-name-@. 
@2 data-name-1 PICTURE X(12). 
@2 data-name-2 PICTURE X(12). 
@2 data-name-3 PICTURE X(12). 
@2 data-name-4 PICTURE X(12). 
82 data-name-5 PICTURE 9(@6). 
02 data-name-6 PICTURE 9(@8). 
@2 data-name-7 PICTURE X(12). 
@2 data-name-8 PICTURE 9(@4). 
@2 data-name-9 PICTURE X. 
G2 data-name-19 PICTURE XX. 
@2 data-name-11 PICTURE 9(@6). 


SYMBOLIC QUEUE 
SYMBOLIC SUB-QUEUE-1 
SYMBOLIC SUB-QUEUE-2 
SYMBOLIC SUB-QUEUE-3 
MESSAGE DATE 
MESSAGE TIME 
SYMBOLIC SOURCE 

TEXT LENGTH 

END KEY 

STATUS KEY 

MESSAGE COUNT 


Note: In the preceding listing, the information under “Comment” is for 
clarification and is not part of the description. 


Record-description entries following an input CD implicitly redefine this record. The 


_ entries must describe a record of exactly 87 characters for the standard CD. (Literal-1 is 


a numeric literal representing the size of the conversation area in characters.) 


Data-names 1 through 11 must be unique. Within this series, any data-name can be 
replaced by the reserved word FILLER. 


The input CD information constitutes the communication between the MCS and the 


program about the message being handled. This information is not displayed on the 
terminal as part of the message. 


INITIAL 


. Inasingle program, the INITIAL clause can be specified in only one CD. The 


INITIAL clause must not be used in a program that specifies the USING phrase in the 
PROCEDURE DIVISION header. 


If the MCS attempts to schedule a program lacking an IN ITIAL clause, the results are 
undefined. 


8600 0296-000 


COMMUNICATION SECTION 


data-name-1 through data-name-4 


The data items referenced by data-name-1, data-name-2, data-name-3, and data-name-4 
contain symbolic names designating queues, subqueues, and so on. All symbolic names 
must follow the rules for the formation of system-names and must have been previously 
defined to the MCS. 


The contents of the data items referenced by data-name-2, data-name-3, and 
data-name-4, when not being used, must contain spaces. 


A RECEIVE statement causes the serial return of the next message or a portion of a 
message from the queue as specified by the entries in the CD. 


If, during execution of a RECEIVE statement, a message from a more specific source 

is needed, the contents of the data item referenced by data-name-1 can be made 

more specific by the use of the contents of the data items referenced by data-name-2, 
data-name-3, and data-name-4. When a given level of the queue structure is specified, all 
higher levels must also be specified. 


If any levels of the queue hierarchy are not specified, the MCS determines the next 
message or the portion of a message to be accessed. 


After execution of a RECEIVE statement, the contents of the data items referenced by 
data-name-1 through data-name-4 contain the symbolic names of all levels of the queue 
structure. 


Whenever a program is scheduled by the MCS to process a message, the symbolic 
names of the queue structure that demanded this activity are placed in the data items 
referenced by data-name-1 through data-name-4 of the CD associated with the INITIAL 
clause, as applicable. In all other cases, the contents of the data items referenced by 
data-name-1 through data-name-4 of the CD associated with the INITIAL clause contain 
spaces. 


The symbolic names are inserted, or the initialization to spaces is completed, prior to the 
execution of the first PROCEDURE DIVISION statement. . 


- The execution of a subsequent RECEIVE statement naming the same contents of the 
data items referenced by data-name-1 through data-name-4 returns the message that 


caused the program to be scheduled. Only at that time is the remainder of the CD 
updated. . 


data-name-5 


Data-name-5 has the format YYMMDD (year, month, day). The contents represent the 
date on which the MCS recognizes that the message is complete. 


The contents of the data item referenced by data-name-5 are only updated by the MCS 
as part of the execution of a RECEIVE statement. 
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data-name-6 


The contents of data-name-6 have the format HHMMSSTT (hours, minutes, seconds, 
hundredths of a second). The contents represent the time at which the MCS recognizes 
that the message is complete. - 


The contents of the data item referenced by data-name-6 are only updated by the MCS 
as part of the execution of a RECEIVE statement. 


data-name-7 


During execution of a RECEIVE statement, the MCS provides, in the data item 
referenced by data-name-7, the symbolic name of the communication terminal that 
is the source of the message being transferred. However, if the symbolic name of 
the communication terminal is not known to the MCS, the contents of the data item 
referenced by data-name-7 contain spaces. 


data-name-8 


The contents of the data item referenced by data-name-8 indicate to the MCS that 
the number of character positions filled as a result of the execution of the RECEIVE 
statement. 


data-name-9 


The contents of the data item referenced by data-name-9 are set only by the MCS as 
part of the execution of a RECEIVE statement, according to the following rules: 
¢ When the RECEIVE MESSAGE phrase is specified, the following action is taken: 


- If an end-of-group indicator has been detected, the contents of the data item 
referenced by data-name-9 are set to 3. 


'—  Jfan end-of-message indicator has been detected, the contents of the data item 
referenced by data-name-9 are set to 2. 


- Ifless than a whole message is transferred, the contents of the data item 
referenced by data-name-9 are set to 0. 


e When the RECEIVE SEGMENT phrase is specified, the following action is taken: 


— Ifan end-of-group indicator has been detected, the contents of the data item 
referenced by data-name-9 are set to 3. 


— Ifan end-of-message indicator has been detected, the contents of the data item 
referenced by data-name-9 are set to 2. 


— Ifan end-of-segment indicator has been detected, the contents of the data item » 
referenced by data-name-9 are set to 1. 


- Ifless than a message segment is transferred, the contents of the data item 
referenced by data-name-9 are set to 0. 


e When more than one of the preceding conditions is satisfied simultaneously, the rule 
first satisfied in the order listed determines the contents of the data item referenced 
by data-name-9. i 


8600 0296-000 


COMMUNICATION SECTION 


data-name-1 0 


The contents of the data item referenced by data-name-10 indicate the status condition 
of the previously executed RECEIVE, ACCEPT MESSAGE COUNT, ENABLE INPUT, 
or DISABLE INPUT statements. 


The actual association between the contents of the data item referenced by 
data-name-10 and the status condition itself is defined in Figure 14-1. 


For the 01-level, Figure 14-1 indicates the possible contents of the data items referenced 
by data-name-10 for Format 1 and by data-name-3 for Format 2 at the completion of each 


statement shown. An X on a line in a statement column indicates that the associated 
code shown for that line is possible for that statement. 


— 
- 
© 
co 
—_ 
& 
a 
vu 
par 
» 
P| 
Oo 
<= 
wary 
_ 
= 

—— 
—_ 
> 
a. 
=z 
mH 
had 
4 
[aa] 
<x 
=z 
uJ 


ovo 
ne] 
oO 
(8) 
> 
3) 
ard 
7%) 
p=] 
ae) 
c 
ee) 
Yn 


te 

x 

| ol 

an | 

oS 

uJ 

a 

ca 

< 

” 

a 

No error detected. Action completed. 

18 Destination is disabled. Action 
completed. 
tite 

X X unknown or access to queue denied by 
system. No action taken. 

X Content of DESTINATION COUNT clause invalid. 
No action taken. 

ry tx] xd x Password invalid. No enabling/disabling 
action taken. 
X Character count greater than length 

of sending field. No action taken. 


Figure 14-1. Communication Status Condition in the 01-level 


nae ENABLE OUTPUT 
a DISABLE INPUT (without terminal) 


Destination unknown. or access thereto 
denied by system. No action taken for 
unknown destination. Data-name-4 
(ERROR KEY) indicates unknown. 


X 


Scemeaci 
os ae ES ACCEPT MESSAGE COUNT: 


One or more queues or subqueues 
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data-name-11 


The contents of the data item referenced by data-name-11 indicate the number of 
messages that exist in a queue, sub-queue-1, and so forth. The MCS updates the 
contents of the data item referenced by data-name-11 only as part of the execution of an 
ACCEPT statement with the COUNT phrase. 


See Also 


Refer to “PROCEDURE DIVISION Header” in Section 8, “PROCEDURE DIVISION 
Concepts,” for information about the restrictions for a program with a USING clause in 
the header. 


CD Format 2 


CD cd-name FOR OUTPUT 
[ ; DESTINATION COUNT IS data-name-1 | 
[; TEXT LENGTH IS data-name-2 | 


[; STATUS KEY IS data-name-3 | 


; DESTINATION TABLE OCCURS integer-2 TIMES 
[ ; INDEXED BY index-name-1 [ index-name-2 ] ...] 


[; ERROR KEY IS data-name-4 | 
[ ; SYMBOLIC DESTINATION IS data-name-5 | 


[ ; CONVERSATION AREA IS data-name-6 SIZE IS literal-1 | 


Explanation of CD Format 2 
ACD entry must appear only in the COMMUNICATION SECTION. 


If none of the optional clauses of the CD are apes a 01-level data-description entry 
must follow the CD entry. 
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For each standard-defined output CD, a record area of contiguous standard data-format 
characters is allocated according to the following formula: 


19 + 13 * integer-2 


The first three words of the record area define the DESTINATION COUNT clause, the 
TEXT LENGTH clause, and the STATUS KEY clause. Note that when the 01-level data 
description is used instead of the optional clauses, the destination table is assumed to 
occur only once and any remaining data greater than 5 words (80 characters) is assumed 
to define the conversation area. 


For the standard-defined CD, the record area is defined as follows: 


e The DESTINATION COUNT clause defines data-name-1 as the name of adataitem - 
whose implicit description is an integer without an operational sign. The data item 
occupies positions 1 through 4 in the record. 


e The TEXT LENGTH clause defines data-name-2 as the name of an elementary data 
item whose implicit description is an integer of 4 digits without an operational sign. 
The data item occupies character positions 5 through 8 in the record. 


e The STATUS KEY clause defines data-name-3 as the name of an elementary, 
alphanumeric data item of 2 characters that occupies positions 9 and 10 in the 
record. 


e Character positions 11 through 23 and every set of 13 characters thereafter form 
table items of the following description: 


- The ERROR KEY clause defines data-name-4 as the name of an elementary, 
alphanumeric data item of 1 character. 


- The SYMBOLIC DESTINATION clause defines data-name-5 as the name of an 
elementary, alphanumeric data item of 12 characters. 


e The CONVERSATION AREA clause contains user-defined text and is valid only 
when the USAGE BINARY clause is used. Refer to Volume 2 for information. 


Use of the preceding clauses results in a record with an implicit description that is 
a to the following standard CD definition: 


Implicit Description Comment 


G1 data-name-@. 


@2 data-name-1 PICTURE 9(@4). DESTINATION COUNT 
82 data-name-2 PICTURE 9(@4). TEXT LENGTH 
82 data-name-3 PICTURE XX. STATUS KEY 
G2 data-name OCCURS integer-2 TIMES. DESTINATION TABLE 
93 data-name-4 PICTURE X. ERROR KEY 
3 data-name-5 PICTURE X(12). SYMBOLIC DESTINATION 


Note: In the preceding listing, the information under “Comment” is for 
clarification and is not part of the description. 
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14-14 


Record descriptions following an output CD implicitly redefine this record. Multiple 
redefinitions of this record are permitted; however, only the first redefinition can contain 
VALUE clauses. 


Data-name-1 through data-name-6 must be unique. 


If the DESTINATION TABLE OCCURS clause is not specified, one ERROR KEY and . 
one SYMBOLIC DESTINATION clause are assumed. In this case, neither subscripting 
nor indexing is permitted when these data items are referenced. 


If the DESTINATION TABLE OCCURS clause is specified, data-name-4 and 
data-name-5 can be referenced only by subscripting or indexing. 


In the 01-level, the value of the data item referenced by data-name-1 and integer-2 must 
be 1. In the 02-level, no restriction exists on the value of the data item referenced by 
data-name-1 and integer-2. 


The nature of the output CD information is such that it is not sent to the terminal but 
constitutes the communication between the program and the MCS about the message 
being handled. 


During execution of a SEND, an ENABLE OUTPUT, or a DISABLE OUTPUT 
statement, the contents of the data item referenced by data-name-1 indicate indicate to 
the MCS the number of symbolic destinations to be used from the area referenced by 
data-name-5. 


The MCS finds the first symbolic destination in the first occurrence of the area 
referenced by data-name-5, the second symbolic destination in the second occurrence of 
the area referenced by data-name-5, and so on, up to and including the occurrence of the 
area referenced by data-name-5 indicated by the contents of data-name-1. 


If, during execution of a SEND, an ENABLE OUTPUT, or a DISABLE OUTPUT 
statement, the value of the data item referenced by data-name-1 is outside the range 1 
through integer-2, an error condition is indicated and the execution of the SEND, the 
ENABLE OUTPUT, or the DISABLE OUTPUT statement is terminated. 


You must ensure that the value of the data item referenced by data-name-1 is valid 
at the time of the execution of the SEND, the ENABLE OUTPUT, or the DISABLE 
OUTPUT statement. 


As part of the execution of a SEND statement, the MCS interprets the contents of the 


data item referenced by data-name-2 to be your indication of the number of leftmost 
character positions of the data item referenced by the associated SEND identifier from 
which data is to be transferred. . 


Each occurrence of the data item referenced by data-name-5 contains a symbolic 
destination previously known to the MCS. These symbolic destination names must follow 


the rules for the formation of system-names. 


The contents of the data item referenced by data-name-3 indicate the status condition of » 


the previously executed SEND, ENABLE OUTPUT, or DISABLE OUTPUT statements. 
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The association between the contents of the data item referenced by data-name-3 and 
the status condition itself is defined in Figure 14-2. 


If, during execution of a SEND, an ENABLE OUTPUT, or a DISABLE OUTPUT 
statement, the MCS determines that any specified destination is unknown or chooses 
to deny the program access to any destination, then the contents of the data item 
referenced by data-name-3 and all occurrences of the data items referenced by 
data-name-4 are updated. 


When the contents of the data item referenced by data-name-4 are equal to 1, this value 
indicates that either the associated value in the area referenced by data-name-5 has not 
been defined previously to the MCS, or that the MCS has been denied access to this 
destination. Otherwise, the contents of the data item referenced by data-name-4 are set 
to 0. 


For the 02-level, Figure 14-2 indicates the possible contents of the data items referenced 
by data-name-10 for Format 1 and by data-name-3 for Format 2 at the completion of each 
statement shown. An X on a line in a statement column indicates that the associated 
code shown for that line is possible for that statement. 
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14-16 


One or more destinations unknown, 

or access thereto denied by system. 
Action completed for known destinations. 
No action taken for unknown destinations. 


Data-name-4 (ERROR KEY) indicates 
known or unknown (includes system 
denied access). 


One or more queues or subqueues 
unknown, or access to queue denied by 
system. No action taken. 


The source is unknown, or access 
thereto denied by the system. 
No action taken. 


30 Content of DESTINATION COUNT clause invalid. 
No action taken. 


Password invalid. No enabling/disabling 
action taken. 


Character count greater than length 
of sending field. No action taken. 


Partial segment with either zero 
character count or no sending area 
specified. No action taken. 


Figure 14-2. Communication Status Key Condition in the 02-level 


Example 


Example 14-2 is a sample program that uses some of the communication module 
constructs. The associations of physical terminals with specific, named input and output 
queues and the appropriate passwords (keys) are maintained by the DCILIBRARY. 


_ The program enables output to the two algae auscnied with OUT-QUEUE-1 


and OUT-QUEUE-2 by using the password SIMON1. It then sends the message 
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TERMINALS ENABLED OUTPUT to both. The program enables input from the 
terminal associated with IN-QUEUE-1 and TERMINAL #1 by using the password 
SIMON1. It receives one message from that terminal. The program then enables input 
from the terminal associated with IN-CQUEUE-2 and TERMINAL #2 by using the 
password SIMON 1. It receives one message from that terminal. It sends the following 
messages to both terminals, using keywords ESI and EMI for end indicators: 


SEGMENT INITIATED-CONTINUED 
-MSG COMPLETE. 


The program sends the following messages to both terminals, using the identifier 
END-FLAG to contain the end indicator. 


SEGMENT INITIATED-CONTINUED 
-MSG COMPLETE. 
-GROUP COMPLETE. 


Then the program sends the message ONLY TERMINAL OUT-QUEUE-1 SHOULD 
RECEIVE THIS MESSAGE only to the terminal associated with OUT-QUEUE-1. It 
finally disables output and input to both terminals by using the password SIMON1. 


98198 IDENTIFICATION DIVISION. 
@2286 ENVIRONMENT DIVISION. 
83208 DATA DIVISION. 

B400G WORKING-STORAGE SECTION. 


@4100 77 END-FLAG PIC 9. 

96200 @1 ENABLE-MSG PIC X(24) VALUE “TERMINALS ENABLED OUTPUT". 
@7900 G1 ONE-TERMINAL-MSG PIC X(53) VALUE 

Q8200 "ONLY TERMINAL OUT-QUEUE-1 SHOULD RECEIVE THIS MESSAGE". 
98500 G1 SEG-INIT PIC X(17) VALUE “SEGMENT INITIATED". 

89808 G1 SEG-CONT PIC X(1@) VALUE “-CONTINUED". 

99190 1 MSG-COMP PIC X(14) VALUE "-MSG COMPLETE.". 

99200 G1 GROUP-COMP PIC X(16) VALUE "-GROUP COMPLETE.". 

19000 1 MSG-1 PIC X(18@) . 


20700 COMMUNICATION SECTION. 

20898 CD CM-INQUE-1 INPUT. 

20988 @1 INQUE-1-RECORD. 

21008 |§ @2 QUEUE-SET PIC X(12). 

21288 @2 FILLER PIC X(36) VALUE SPACES. 
21388 @2 FILLER PIC X(14). 

21406 @2 SYM-SOURCE PIC X(12). 

21586 @2 IN-LENGTH PIC 9999. | 

21680 @2 END-KEY PIC X. 

21726 @2 IN-STATUS PIC XX. 

21820 @2 MSG-COUNT PIC 9(6). 

21986 CD CM-OUTQUE-1 OUTPUT 

22008 DESTINATION COUNT DEST-COUNT 
22180 TEXT LENGTH OUT~LENGTH 

22200 STATUS KEY OUT-STATUS 

22300 DESTINATION TABLE OCCURS 2 TIMES INDEXED BY 11 
22400 ERROR KEY ERR-KEY 

22588 DESTINATION SYM-DEST. 


Example 14-2. Program Sample: Maintaining Associations of Physical Terminals with 
Queues 
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22600 PROCEDURE DIVISION. 

22890 ENABLE-MSGS. 

23000 MOVE 2 TO DEST-COUNT. 

23500 MOVE "OUT-QUEUE-1" TO SYM-DEST (1). 

240008 MOVE "OUT-QUEUE-2" TO SYM-DEST (2). 

24180 ENABLE OUTPUT CM-OUTQUE-1 WITH KEY "SIMON1". 
24460 WAIT (19). 

24500 SEND-MSG. 

24620 MOVE 24 TO OUT-LENGTH. 

24720 SEND CM-OUTQUE-1 FROM ENABLE-MSG WITH EMI. 
28008 RECEIVE-MSGS. 

28200 MOVE "IN-QUEUE-1" TO QUEUE-SET. 

28400 MOVE "TERMINAL #1" TO SYM-SOURCE. 

28450 ENABLE INPUT TERMINAL CM-INQUE-1 WITH KEY "SIMONI". 
28460 WAIT (15). 

28500 RECEIVE CM-INQUE-1 MESSAGE INTO MSG-1 NO DATA DISPLAY "ERR1". 
29200 DISPLAY MSG-1. 

32200 MOVE "IN-QUEUE-2" ‘TO QUEUE-SET. 

31020 MOVE "TERMINAL #2" TO SYM-SOURCE. 

31509 ENABLE INPUT TERMINAL CM-INQUE-1 WITH KEY "SIMONI". 
31620 WAIT (15). 

31708 RECEIVE CM-INQUE-1 SEGMENT INTO MSG-1 NO DATA DISPLAY "ERR2". 
31829 DISPLAY MSG-1. 

50700 SEGMENTED-MSGS-91. 

59980 MOVE 17 TO OUT-LENGTH. 

51000 SEND CM-OUTQUE-1 FROM SEG-INIT. 

51180 MOVE 18 TO OUT-LENGTH. 

51200 SEND CM-OUTQUE-1 FROM SEG-CONT WITH ESI. 

51300 MOVE 14 TO OUT-LENGTH. 

51490 SEND CM-OUTQUE-1 FROM MSG-COMP WITH EMI. 

51500 SEGMENTED-MSGS-22. 

51790 MOVE @ TO END-FLAG. 

51890 MOVE 17 TO OUT-LENGTH. 

51990 SEND CM-OUTQUE-1 FROM SEG-INIT WITH END- FLAG. 
52000 MOVE 1 TO END-FLAG. 

52109 MOVE 18 TO OUT-LENGTH. 

52200 SEND CM-OUTQUE-1 FROM SEG-CONT WITH END-FLAG. 
52308 MOVE 2 TO END-FLAG. 

52490 MOVE 14 TO OUT-LENGTH. 

52500 SEND CM-OUTQUE-1 FROM MSG-COMP WITH END-FLAG. 
52620 MOVE 3 TO END-FLAG. 

52700 MOVE 16 TO OUT-LENGTH. 

52800 SEND CM-OUTQUE-1 FROM GROUP-COMP WITH END-FLAG. 
53700 SINGLE-TERMINAL-MSG. 

53800 MOVE 1 TO DEST-COUNT. 

53998 MOVE 53 TO OUT-LENGTH. 

54000 _ SEND CM-OUTQUE-1 FROM ONE-TERMINAL-MSG WITH EMI. 
54300 DISABLE-MSGS. 

54350 WAIT (10). 

54400 MOVE 2 TO DEST-COUNT. 

54500 MOVE “OUT-QUEUE-1" TO SYM-DEST (1). 


Example 14—2. Program Sample: Maintaining Associations of Physical Terminals with 
Queues (cont.) 
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54609 MOVE "OQUT-QUEUE-2" TO SYM-DEST (2). 

54706 | DISABLE OUTPUT CM-OUTQUE-1 WITH KEY "SIMON1". 

55828 MOVE "TERMINAL #1" TO SYM-SOURCE. 

55108 DISABLE INPUT TERMINAL CM-INQUE-1 WITH KEY "SIMON1". 
55200 MOVE "TERMINAL #2" TO SYM-SOURCE. ) 

55388 DISABLE INPUT TERMINAL CM-INQUE-1 WITH KEY "SIMON1". 
56308 STOP RUN. 


Example 14-2. Program Sample: Maintaining Associations of Physical Terminals with 
Queues (cont.) 


PROCEDURE DIVISION in the Communication Module 


The following constructs apply to the PROCEDURE DIVISION when the 
communication module is used. 


Note: Refer to Volume 2 for information about using PROCEDURE 
DIVISION statements with COMS headers. 
ACCEPT MESSAGE COUNT Statement 


The ACCEPT MESSAGE COUNT statement makes available the number of messages 
in a queue. 


The general format of this statement is as follows: 


ACCEPT cd-name MESSAGE COUNT 


Explanation of Format 
Cd-name must reference an input CD. 


The ACCEPT MESSAGE COUNT statement causes the MESSAGE COUNT field 
specified for cd-name to be updated to indicate the number of messages present in a 
queue, sub-queue-1, and so on. 


When the ACCEPT MESSAGE COUNT statement is executed, the contents of the 
area specified by a communication-description (CD) entry must contain at least the 
name of the symbolic queue to be tested. When the condition is tested, the contents of 
the data items referenced by data-name-10 (STATUS KEY phrase) and data-name-11 
(MESSAGE COUNT phrase) of the area associated with the communication description 
(CD) are updated as necessary. 


8600 0296-000 | , 14-19" 


COMMUNICATION SECTION 


See Also 
' Refer to “DATA DIVISION in the Communication Module” earlier in this section for 


information about the STATUS KEY and MESSAGE COUNT phrases in Format 1 of 
the CD entries. 


DISABLE Statement 
The DISABLE statement notifies the MCS to inhibit data transfer between specified 
output queues and destinations for output or to inhibit data transfer between specified 


sources and input queues for input. 


The general format of this statement is as follows: 


DISABLE { 


INPUT \ [| TERMINAL | cd-name WITH KEY 


identifier-1 
OUTPUT J 


literal-1 


Explanation of Format 


The DISABLE statement provides a logical disconnection between the MCS and the 
specified sources or destinations. When this logical disconnection has already occurred 
or is handled by some means external to this program, the DISABLE statement is not 
required in this program. The logical path for the transfer of data between the COBOL 
programs and the MCS is not affected by the DISABLE statement. 


When the logical disconnection specified by the DISABLE statement has already 
occurred, is handled by some means external to this program, or is denied by the MCS, 
the status-key data item in the area referenced by cd-name is updated. 


INPUT 


When the INPUT phrase with the optional word TERMINAL is specified, the logical 
path between the source and all associated queues and subqueues is deactivated. Only 
the contents of the data item referenced by data-name-7 (SYMBOLIC SOURCE phrase) 
of the area referenced by cd-name are meaningful. 


When the INPUT phrase without the optional word TERMINAL is specified, the logical 
paths for all sources associated with the queues and subqueues specified by the contents 
of data-name-1 (SYMBOLIC QUEUE phrase) through data-name-4 (SYMBOLIC 
SUB-QUEUE-8 phrase) of the area referenced by cd-name are deactivated. 


OUTPUT 


When the OUTPUT phrase is specified, the logical path for the destination or the 
logical paths for all destinations specified by the contents of the data item referenced by 
data-name-5 (SYMBOLIC DESTINATION phrase) of the data referenced by cd-name 
are deactivated. 
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cd-name 


The cd-name must refer to an input CD when the INPUT phrase is specified and must 
refer to an output CD when the OUTPUT phrase is specified. 


literal-1 or identifier-1 


Literal-1 or the contents of the data item referenced by identifier-1 must be defined as 
alphanumeric. 


The MCS handles a password of between 1 and 10 characters, inclusive. Literal-1 or the 
content of the data item referenced by identifier-1 is transferred to the MCS according 
to the rules for the MOVE statement. The MCS receives the password in an area 
considered to be an elementary, alphanumeric data item that is 10 characters long. 


See Also 


For information about the location of the status-key data item, refer to “CD Format 1” 
and “CD Format 2” earlier in this section. 


ENABLE Statement 


The ENABLE statement notifies the MCS to allow data transfer between specified 
output queues and destinations for output or to allow data transfer between specified 
sources and input queues for input. 


The general format of this statement is as follows: 


INPUT 


ENABLE { OUTPUT 


\ [ TERMINAL | cd-name WITH KEY { 


identifier-1 \ 
literal-i 


Explanation of Format 


The ENABLE statement provides a logical connection between the MCS and the - 
specified sources or destinations. When this logical connection is already present or 

is handled by some means external to this program, the ENABLE statement is not 
required in this program. The logical path for the transfer of data between the COBOL 
programs and the MCS is not affected by the ENABLE statement. 


When the logical connection specified by the ENABLE statement already exists, is 


to be handled by some means external to this program, or is denied by the MCS, the 
status-key data item in the area referenced by cd-name is updated. 
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INPUT 


When the INPUT phrase with the optional word TERMINAL is specified, the logical 
path between the source and all associated queues and subqueues that are already 
enabled is activated. Only the contents of the data item referenced by data-name-7 
(SYMBOLIC SOURCE phrase) of the area referenced by cd-name are meaningful to the 
MCS. 


When the INPUT phrase without the optional word TERMINAL is specified, the logical 
paths for all sources associated with the queue and subqueues specified by the contents 
of data-name-1 (SYMBOLIC QUEUE phrase) through data-name-4 (SYMBOLIC 
SUB-QUEUE phrase) of the area referenced by cd-name are activated. 


OUTPUT 


When the OUTPUT phrase is specified, the logical paths for all destinations specified by 
the contents of the data item referenced by data-name-5 (SYMBOLIC DESTINATION 
phrase) of the area referenced by cd-name are activated. 


cd-name 


Cd-name must refer to an input CD when the INPUT phrase is specified and must refer 
to an output CD when the OUTPUT phrase is specified. 


literal-1 or identifier-1 


Literal-1 or the contents of the data item referenced by idenanicr: 1 must be defined as 
alphanumeric. 


The MCS handles a password of between 1 and 10 characters, inclusive. Literal-1 or 
the contents of the data item referenced by identifier-1 are transferred to the MCS 
according to the rules for the MOVE statement. The MCS receives the password in an 
area considered to be an elementary, alphanumeric data item that is 10 characters long. 


_ See Also 


For information about the location of the status-key data item, refer to “CD Format 1” 
and “CD Format 2” earlier in this section. 


RECEIVE Statement 


14-22 


The RECEIVE statement makes a message, a message segment (or a portion of a 
message or a segment), and pertinent information about the data available to the 
COBOL74 program from a queue maintained by the MCS. The RECEIVE statement 
enables a specific imperative-statement when no data is available. 


When execution of a RECEIVE statement returns a portion of a message, only the 


subsequent execution of RECEIVE statements in that run unit can cause 4 remaining 
portion of the message to be returned. 
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After execution of a STOP RUN statement, the disposition of a remaining portion of 
a message partially obtained in that run unit is defined by the data communications 
interface (DCI) library. 


The general format of this statement is as follows: 


MESSAGE 


RECEIVE cd-name { SEGMENT 


} INTO identifier-1 


[ ; NO DATA imperative-statement | 


Explanation of Format 


The data items identified by the input CD are updated appropriately by the MCS at each 
execution of a RECEIVE statement. 


cd-name 
Cd-name must reference an input CD. 


The contents of the data items specified by data-name-1 (SYMBOLIC QUEUE phrase) 
' through data-name-4 (SYMBOLIC SUB-QUEUE-3 phrase) of the area referenced by 
cd-name designate the queue structure containing the message. 


MESSAGE 


When the MESSAGE phrase is used, end-of-segment indicators are ignored and the 
following rules apply to the data transfer: 


e Ifamessage is the same size as the area referenced by identifier-1, the message is 
stored in the area referenced by identifier-1. 


e Ifamessage size is smaller than the area referenced by identifier-1, the message is 
aligned to the leftmost character position of the area referenced by identifier-1 with 
no zero fill. 


e Ifamessage size is larger than the area referenced by identifier-1, the message 

fills the area referenced by identifier-1 from left to right, starting with the leftmost 
character of the message. In the 01-level, the disposition of the remainder of the 
message is undefined. 


In the 02-level, the remainder of the message can be transferred to the area 

' referenced by identifier-1. Subsequent RECEIVE statements refer to the same 
queue, subqueue, and so on. The remainder of the message, in applying the 
preceding bulleted rules, is treated as a new message. 
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A single execution of a RECEIVE statement never returns more than a single message 
to the data item referenced by identifier-1. However, the MCS does not pass any portion 
of a message to the object program until the entire message is available in the input 
queue, even if the SEGMENT phrase of the RECEIVE statement is specified. 


SEGMENT 
When the SEGMENT phrase is used, the following rules apply: 


e Ifasegment is the same size as the area referenced by identifier-1, the segment i is 
stored in the area referenced by identifier-1. 


e Ifthe segment size is smaller than the area salsrenued by identifier-1, the segment is 
aligned to the leftmost character position of the area referenced by identifier-1 with 
no space fill. 


e Ifasegment size is greater than dite area referenced by identifier-1, the segment 
fills the area referenced by identifier-1 from left to right, starting with the leftmost 
character of the segment. The remainder of the segment can be transferred to the 
area referenced by identifier-1. Subsequent RECEIVE statements call out the same 
queue, subqueue, and so on. 


e Ifthe text to be accessed by the RECEIVE statement has an end-of- -message ~ 
indicator (EMI) or end-of-group (EGJ) indicator associated with it, the existence of 
an end-of-segment indicator (ESI) associated with the text is implied and the text is 
treated as a message segment. 


A single execution of a RECEIVE statement never returns more than a single segment 
to the data item referenced by identifier-1. However, the MCS does not pass any portion 
of a message to the object program until the entire message is available in the input 
queue, even if the SEGMENT phrase of the RECEIVE statement is specified. 


identifier-1 


The message, the message segment, or the portion of a message or a segment is 
transferred to the receiving character positions of the area referenced by identifier-1 and 
is aligned to the left without space-fill. 


During execution of a RECEIVE statement, the MCS makes data available in the 


data item referenced by identifier-1, and control is transferred to the next executable 
statement, whether or not the NO DATA phrase is specified. 
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NO DATA 


During execution of a RECEIVE statement, the MCS does not make data available in 
the data item referenced by identifier-1, and the following action takes place: 


e ifthe NO DATA phrase is specified, the receive operation is terminated with the 
indication that action is complete and the imperative-statement in the NO DATA 
phrase is executed. 


e Ifthe NO DATA phrase is not specified, execution of the object program is 
suspended until data is made available in the data item referenced by identifier-1. 


e Ifone or more queues or subqueues is unknown to the MCS or if the MCS denies 
this program access to a queue or subqueue, control passes to the next executable 
statement whether or not the NO DATA phrase is specified. (See Figures 14—1 and 
14~2 earlier in this section.) 


The imperative-statement can be the NEXT SENTENCE phrase. 


See Also 


Refer to “DATA DIVISION in the Communication Module” earlier in this section for 
information about the data items identified by the input CD. 


SEND Statement 


The SEND statement releases a message, a message segment, or a portion of a message 
to one or more output queues maintained by the MCS. 


A single execution of a Format 1 SEND statement releases only a single portion of a 
message or a message segment to the MCS. A single execution of a Format 2 SEND 
statement never releases to the MCS more than a single message or a single message 
segment as indicated by the contents of the data item referenced by identifier-2 or 
by the specified end-of-segment indicator (ESD, end-of-message indicator (EMD), or 
end-of-group indicator (EGI). However, the MCS does not transmit any portion of a 
message to a communications device until the entire message is placed in the output 
queue. 


The general formats of this statement are as follows: 


Format 1 


SEND cd-name FROM identifier-1 
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Format 2 


WITH identifier-2 
WITH ESI 

WITH EMI 
WITH EGI 


SEND cd-name | FROM identifier-1 | 


identifier-3 LINE 
{integer} Loins | 

mnemonic-name 
ces 


se 


AFTER \ ADVANCING 


Explanation of Formats 
Cd-name must reference an output CD. 


Identifier-1 must be the data-name of the area where the data is made available to the 
MCS so that the data can be sent. 


Identifier-2 must reference a 1-character integer without an operational sign. 
Identifier-3, if used, must be the name of an elementary integer item. 


If a mnemonic-name phrase is used, the name is identified with a particular feature 
specified in the SPECIAL-NAMES paragraph in the ENVIRONMENT DIVISION. 


Integer or the value of identifier-3 can be 0. 


General Rules 


The contents of the data items specified by data-name-1 (SYMBOLIC QUEUE phrase) 
| DATE-WRITTEN of the area referenced by cd-name designate the queue structure 
containing the message. (Refer to “DATA DIVISION in the Communication Module” 
earlier in this section. 


The message, the message segment, or the portion of a message or a message segment is 


to be moved to the SEND character positions of the area referenced by identifier-1 and 
aligned to the left with zero fill. . 


14-26 | . 8600 0296-000 


COMMUNICATION SECTION 


When a receiving communication device (such as a printer or a display screen) is oriented 
to a fixed line size, the following rules apply: 


e Each message or message segment begins at the leftmost character position of the 
physical line. 


e Amessage or a message segment smaller than the physical line size is released to 
appear to be zero-filled to the right. 


e Excess characters of a message or a message segment are not truncated. Characters 
are packed to a size equal to that of the physical line and then are sent to the device. 
This process continues on the next line with the excess characters. 


When a receiving communication device (such as a printer or another computer) is 
oriented to handling variable-length messages, each message or message segment begins 
with the next available character position of the communications device. 


As part of the execution of a SEND statement, the MCS interprets the contents of the . 
data item referenced by data-name-8 (TEXT LENGTH phrase) of the area referenced by 
cd-name to be your indication of the number of leftmost character positions of the data 
item referenced by identifier-1 from which data is to be transferred. 


If the value of data-name-8 (TEXT LENGTH phrase) is 0, no characters of the data item 
referenced by identifier-1 are transferred. 


The value of data-name-8 (TEXT LENGTH phrase) cannot be outside the range 0 
through the size of the data item referenced by identifier-1, inclusive. If the value of 
data-name-8 is outside the range, an error is indicated by the value of the data item 
referenced by data-name-10 (STATUS KEY phrase) in the area referenced by cd-name, 
and no data is transferred. 


As part of the execution of a SEND statement, the contents of the data item referenced 
by data-name-10 (STATUS KEY phrase) of the area referenced by cd-name are roupdated 
by the MCS. 


The effect of special control charactors | in the contents of the data item referenced by 
identifier-1 is undefined. 


Duting the execution of the run unit, the disposition of a portion of a message not ended 
by an EMI or an EGI is undefined. Thus, the message does not logically exist for the 
MCS and cannot be sent to a destination. 


_ After the execution of a STOP RUN statement, any portion of a message transferred 
from the run unit as a result of a SEND statement, but not terminated by an EMI or an 
EGI, is purged from the system. Thus, no portion of the message is sent. 


Once the execution of a SEND statement has released a portion of a message to the 


MCS, only the subsequent execution of SEND statements in the same run unit can cause 
the remaining portions of the message to be released. 
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Format 2 


The contents of the data item referenced by identifier-2 indicate that the contents of the 
data item referenced by identifier-1 are to have an associated end-of-segment indicator 
(ESD, end-of-message indicator (EMI), or end-of-group indicator (EGD according to the 
schedule in Table 14~1. . 


Table 14-1. Transmission Indicator Schedule 


Identifier-2 identifier-1 Meaning 


No indicator No indicator 


ESI An end-of-segment indicator 


EMI An end-of-message indicator 


EGI An end-of-group indicator 


Any character other than 1, 2, or 3 is interpreted as 0. If the content of the data item 
referenced by identifier-2 is other than 1, 2, or 3 and if identifier-1 is not specified, then 
an error is indicated by the value in the data item referenced by data-name-10 (STATUS 
KEY phrase) in the area referenced by cd-name, and no data is transferred. 


The ESI indicates to the MCS that the message segment is complete, the EMI indicates 
to the MCS that the message is complete, and the EGI indicates to the MCS that the 
group of messages is complete. The MCS recognizes these indicators and establishes the 
appropriate linkage to maintain group, message, and segment control. 


The hierarchy of ending indicators (major to minor) is EGI, EMI, and ESI. An EGI need 
not be preceded by an ESI or an EMI, and an EMI need not be preceded by an ESI. 


The ADVANCING phrase enables you to control the vertical positioning of each message 
or message segment on a communications device where vertical positioning applies. If 
vertical positioning is not applicable on the device, the MCS ignores the specified or 
implied vertical positioning. 


If identifier-2 is specified and the contents of the data item referenced by identifier-2 are 
equal to 0, the ADVANCING phrase is ignored by the MCS. 


- Ona device where vertical positioning applies and the ADVANCING phrase is not 


specified, automatic advancing occurs as if you had specified the AFTER ADVANCING i 
LINE phrase. 
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If the ADVANCING phrase is implicitly or explicitly specified and vertical positioning 
applies, the following rules apply: 


If identifier-3 or integer is specified, characters transmitted to the communications 
device are repositioned vertically downward the number of lines equal to the value 
associated with the data item referenced by identifier-3 or integer. 


If mnemonic-name is specified, characters transmitted to the communications device 
are positioned according to the rules specified for that communications device. 


If the BEFORE phrase is used, the message or the message segment is represented 
on the communications device before the characters are repositioned vertically, 
according to the rules explained in the preceding list items. 


If the AFTER phrase is used, the message or the message segment is represented on 
the communications device after the characters are repositioned vertically, according 
to the rules explained in the preceding list items. 


If the PAGE phrase is specified, characters transmitted to the communications 
device are represented on the device before or after the device is repositioned to the 
next page (depending on the phrase used). If the PAGE phrase is specified but has 
no meaning in conjunction with a specific device, then advancing occurs as if you had 
specified either the BEFORE ADVANCING 1 LINE or AFTER ADVANCING 1 
LINE phrase. . 
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Libraries 


Libraries include the capabilities of the Inter-Program Communication (IPC) module 
described in Section 18, “ANSI Inter-Program Communication (IPC).” With the 
exception of the IPC capabilities described i in Section 13, all features described in this 
section are Unisys extensions. 


A library program is a program that provides a procedure or a set of procedures that can 
be called by other programs. The procedure or set of procedures are in object code. 
Therefore, a library program can be thought of as a collection of library objects accessible 
through an entry point. Each library object is accessible to other programs, including 
other library programs. 


The program that calls the library object is called the user program. Libraries cannot 
be called recursively; that is, a called program cannot call another program that, in turn, 
calls the original program. 


labears can be created with, or called from, COBOL programs. Libraries created by. 
COBOL are limited to one entry point. 


See Also 


A detailed discussion of the use of libraries is found in the Task Management Guide; 
familiarity with this material is assumed in the following discussion. 


Creating a Library 


_ The compiler automatically creates a COBOL74 library program, provided that the 
following constraints are true of the library program: 


e Only parameters that are allowed for libraries appear in ‘ie USING phrase of the 
PROCEDURE DIVISION statement. 


e Noconstructs occur in the program that are incompatible with its use as a library. 


COBOL library programs have a single entry point. The name of that entry point is 
PROCEDUREDIVISION, unless the library program contains a program name in the 
PROGRAM-ID clause of the IDENTIFICATION DIVISION and is compiled with the: 
FEDLEVEL compiler control option set to 5. If such is the case, the name described in 
the PROGRAM-ID clause is used as the entry point name. 
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The following code makes a program ineligible for use as a library: 


e AVALUE statement or a RECEIVED BY CONTENT clause on a data item listed in 
the USING clause of the PROCEDURE DIVISION header 


e AUSE AS EXTERNAL PROCEDURE directive in the DECLARATIVES SECTION 
of the PROCEDURE DIVISION 


See Also 
For information about specifying and evaluating levels of COBOL to measure compliance 


with U.S. Government COBOL standards, refer to “FEDLEVEL” in Section 17, 
“Control of the Compilation Process.” 


PROCEDURE DIVISION Header in Library Program 


Parameters are optional in libraries; however, if parameters are used, the library 
program must identify them with a USING clause in the PROCEDURE DIVISION. 


In a COBOL74 library, the USING clause of the PROCEDURE DIVISION header can 
specify the following three types of parameters: 


e Data items passed by reference | 
e Data items passed by reference with type conversion 


e Files passed by reference 


The format of the header is as follows: 


PROCEDURE DIVISION | sie Caen =| 


e€-name 


Explanation of Format 

The data-name must be defined in the LINKAGE SECTION of the program in which the 
PROCEDURE DIVISION header occurs, must have’a 01-level or a 77-level number, and 
must not be a redefined item. 


’ The file-name must be defined in the FILE SECTION of the program. 


15-2 | 8600 0296-000 


Libraries 


Rules for Parameters 


Parameters to the library entry point can be any of the following types: 


COMP 01, 77 INDEX 

BINARY, 01, 77 INTEGER (COMP) 

DISPLAY, 01 REAL 

DOUBLE STRING (DISPLAY) 
FILE | 


Parameters of the form INTEGER (COMP) provide a method to receive parameters 
of type INTEGER. Parameters of the form STRING (DISPLAY) provide a method to 
receive parameters of type STRING. 


All data items that are used as parameters either in a COBOL74 library or in a program 
that calls a COBOL74 library are treated as by-reference parameters. 


Any program that declares parameters RECEIVED BY CONTENT are not library 
capable. The only way for a by-value parameter to be used either in the IPC module or 
in the library extension is with the type INTEGER conversion in the library mechanism. 


When a user program and a library program are both written in COBOL74, the data 
types of the parameters must be the same. 


When the user program and the library programs are written using different 
programming languages, the data types must correspond to one another. 


Because of the constraints imposed by the IPC module, parameter matching has special 
rules for some data items. These special rules for parameter matching are shown in 
Table 15-1. : 


‘Table 15-1. Parameter Matching for Data Items Requiring Special Rules 


COBOL74 Data Type General Data Type . 


01-level COMP or INDEX item EBCDIC array 
77-level COMP or INDEX item HEX array 
01-level BINARY item INTEGER array 


77-level BINARY item with less than 12 INTEGER variable 
digits 


77-\evel BINARY item with 12 or more digits DOUBLE variable 
77-level REAL item REAL variable 


continued 
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Table 15-1. Parameter Matching for Data Items Requiring Special Rules (cont.) 


COBOL74 Data Type General Data Type 
01-level REAL item REAL arrays 


All other cases Parameter-matching conventions follow the 
declared usage of the item. 


There is an important distinction for BINARY, REAL, and DOUBLE items between 
those declared at the 01-level and those declared at the 77-level. The 01-level items 

are unconditionally treated as arrays, whereas the 77-level items are treated as words. 
Thus, a 01-level REAL item is described in the library interface as a REAL ARRAY BY 
REFERENCE, whereas a 77-level REAL item is described as a REAL BY REFERENCE. 


A COBOL74 program receiving a lower-bound parameter from another program must 
declare an extra parameter, a 77-level PIC 9(11) BINARY item. This item name must 

appear in the USING clause immediately following the lower-bound receiving item. In 
addition, the LOWER-BOUNDS clause must not be declared for the receiving item. 


Exiting a Library 


A COBOL library program must have an EXIT PROGRAM statement as a means 

of exiting and returning to the user program. A STOP RUN statement in a library 
program ends both the library and the calling program. A STOP literal statement in a 
library program has no effect on the program and is ignored at execution time. 


The EXIT PROGRAM statement causes program control to be returned to the user 
program at the statement following the statement that called the library. 


The general format of this statement is as follows: 


EXIT PROGRAM . 
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Explanation of Format 

An execution of an EXIT PROGRAM statement in a COBOL74 library causes control 
to be passed from the library to the user program. Execution of an EXIT PROGRAM 
statement in a program that is not called causes the program to act as if the statement 
were an EXIT statement. 


The EXIT PROGRAM statement must appear in a sentence by itself. 


The EXIT PROGRAM sentence must be the only sentence in the paragraph. 
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See Also 


For general information about the EXIT statement, refer to “EXIT” in Section 9, 
“PROCEDURE DIVISION Statements.” 


Securing a Library 


Compiler locking code is provided in the library to ensure data integrity. Because data 
is global to both the user program and the entry point, and because library parameters 
must remain global, the compiler restricts the use of a COBOL library to one user at a 
time. You must wait until the preceding user is finished before you can enter the library. 


If a library program is called by user programs written in other languages and the library 
is declared with the SHARING compiler control option equal to PRIVATE, then the 
LIBRARYLOCK option should be set to TRUE to ensure data integrity. 


Compiler locking code does not allow recursive calls on a library that can result in 
deadlock situations (for example, waiting for the release of a lock that the user himself 
holds). If a recursive or a cyclical call is attempted on a COBOL library with the 
SHARING compiler control one set to SHAREDBYALL, the library terminates the 
attempt. 


See Also 


e For information on providing compiler locking code to maintain data integrity 
for private libraries, refer to “LIBRARYLOCK” in Section 17, “Control of the 
Compilation Process.” . 


e For information on the ways in which a program can be shared when it is called as a 
library, refer to “SHARING” in Section 17, “Control of the Compilation Process.” 


Referring to a Library 


A user program can refer to a library program by using the CALL statement or the 
CANCEL statement. The CALL statement causes program control to pass from the user 
program to the specified entry point of the library. The CANCEL statement cele 
that the operating system terminate the library. 


Library programs written in COBOL or COBOL74 have a single entry point, named 
PROCEDUREDIVISION by default. If a program being called has a PROGRAM-ID 
clause in the IDENTIFICATION DIVISION and has the FEDLEVEL compiler 
control option set to 5, the name appearing in the PROGRAM-ID clause is the entry 
point name. In all other cases, the entry point to COBOL and COBOL74 libraries is 
PROCEDUREDIVISION. 


Other languages have specific syntax for the declaration of entry points. The 
appropriate entry-point-name must be used for calling such libraries. 
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CALL Statement for Libraries 


The library being called can be described in different ways depending on whether 

the library is called with a literal or with an identifier, and depending on whether 

the LIBACCESS attribute is assigned the value BYTITLE (the default) or the value 
BYFUNCTION. Refer to “Library Attributes” later in this section for details about the 
LIBACCESS attribute. 


The general format of a library CALL statement is as follows: 


data-name-4 
file-name-1 
STRING ( data-name-5 ) 
literal-3 INTEGER ( data-name-6 ) 
— oe data-name-7 
file-name-2 


STRING ( data-name-8 ) 


INTEGER ( data-name-9 ) 
[ GIVING data-name-10 | 


[ ON OVERFLOW imperative-statement | 


Explanation of Format 


literal-3 


The contents of literal-3 can be as follows: 


IN 


entry-point-name \ce} | library-name 


The entry-point-name is the name of the entry point in the library or the function being 
called. In IPC calls, this entry-point-name is PROCEDUREDIVISION by default. 


The library-name is a library-title if the LIBACCESS attribute is BYTITLE, and it isa 
function-name if the LIBACCESS attribute is BYFUNCTION. 
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A library-title is the object code file-name of the library that contains the entry point. A 
library-title is meaningful only if the LIBACCESS attribute of the library program is 
BYTITLE (the default value). A library-title can contain a usercode as its first directory 
node, but it cannot contain a family name (for example, ON DISK). 


A function-name is the name by which an established system library is made available to 
users. A function-name is meaningful only if the LIBACCESS attribute of the library 
program is BYFUNCTION. A function-name is limited to a maximum of 17 numeric, 
uppercase, alphabetic characters and must not contain slashes (/) or other special 
characters. 


identifier-3 


Identifier-3 can only contain a library-name. The entry-point-name in a CALL 
identifier-3 statement is always PROCEDUREDIVISION for compatibility with the 
ANSI-74 COBOL Inter-Program Communication (IPC) module. 


Note: In addition to the restrictions for the contents of identifier-3, a 
CALL identifier-3 statement is always significantly less efficient 
in execution-time performance than the equivalent CALL literal-3 
statement. 


USING 


The USING clause identifies data items and files passed as parameters to the library 
procedure and also enables you to manipulate some parameter types with the STRING 
and INTEGER type conversion mechanisms. 


- ‘The usage of data items used as apanistees to the library ony point can be BINARY, 
COME, DISPLAY, DOUBLE, INDEX, or REAL. - 


The STRING (data-name-5) phrase converts the DISPLAY item specified by 
data-name-5 to a string representation so that the item can be passed to a string 
parameter of a library object. The string data type cannot be represented directly 1 in 
COBOL or COBOL74, but appears in other languages such as ALGOL. 


The INTEGER (data-name-6) phrase converts the COMP item specified by data-name-6 
to an integer representation. The compiler generates the object code to pass the 
numeric value of the packed field in a temporary variable as an integer by reference, and 
to store the value of that temporary variable (in the event that the library has modified 
it) back into the original parameter. Data-name-6 must be the name of an elementary 
01-level or 77-level data item declared USAGE COMPUTATIONAL. 


A parameter in a USING clause cannot redefine another item either implicitly in the 
FILE SECTION or explicitly with a REDEFINES clause. Also, 77-level items that have 
been redefined can yield unexpected results. For example, referring to a 77-level item 
in a REDEFINES clause can cause the item to be treated as if it had been declared as a 
01-level item. 
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GIVING (Unisys Extension) 


The GIVING clause allows a typed procedure to be called as a library and stores the 
value of the procedure in data-name-10. 


A library written in languages other than COBOL and COBOL74 can be a typed 
procedure, and thereby return a value. 


The GIVING clause specifies the type of procedure and the destination for the value 
that is returned from the procedure. The procedure type is needed for library linkage 
matching. 


Data-name-10 must specify an elementary numeric item. The rules regarding the 
relationship between the usage of data-name-10, the type of procedure, and the result 
returned by the procedure are described in the following table. 


Usage of data-name-10 Type of Procedure and Result Returned 


77-level USAGE REAL The user program expects the library procedure to be a REAL 
PROCEDURE and the result to be of type REAL. 


77-level USAGE DOUBLE The user program expects the library procedure to be a 
DOUBLE PROCEDURE and the result to be of type DOUBLE. 


All other cases The user program expects the library procedure to be an 
INTEGER PROCEDURE. The result returned is converted at 
execution time into the proper form for storing in 
data-name-10 according to the rules for the COMPUTE 
statement. 


A CALL identifier-3 statement with a GIVING clause —although a supported feature —is 
of marginal use for the following reasons: 


e Atyped entry point cannot be declared in COBOL or COBOL74. 


e The only entry point accessible with such a call is PROCEDUREDIVISION, yet the 
program containing the library cannot be written in COBOL or COBOL74, which are 
the only languages in which such an entry-point-name is expected. 


Effect of Library State on a CALL Statement 
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User programs can be dependent on a library being in its initial or noninitial state on a 
given call to a library. A library is in its initial state the first time any user successfully 
links to it after the library begins executing. 


The state of a library depends on the environment in which the library is used andon 
the value of the SHARING compiler control option in the library itself. Neither of these 
factors is under the control of the individual user programs linking to the library. 


Table 15-2 shows how the value of the SHARING compiler control option affects the 
initial state of the library. | 
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Table 15-2. Effect of SHARING Option Value and Library Initial State on CALL 
Statement 


SHARING Option Value Effect on Library Initial State 
SHAREDBYRUNUNIT The library is in its initial state at the following times: 


e The first time any Program in the run unit calls the 
library 


e = The first time any program in the run unit calls the 
library after a CANCEL statement has been successfully 
performed on the library from within the run unit 


PRIVATE The library is in its initial state at the following times: 


e ach and every time the program uses a CALL 
identifier-3 statement to call the library. This format 
causes the library to start and complete execution every 
time the format is used. 


e = The first time the program uses a CALL literal-3 
statement to call the library. 


e The first time the program calls the library after it has 
successfully canceled the library. 


SHAREDBYALL A temporary library is in its initial state at the following 
times: 


e The first time any program on the system calls the 
library 


e@ The first time any program on the system calls the 
library after the operating system has determined that 
no more users exist and has therefore terminated the 
library 


A permanent library is in its initial state the first time any 
program on the system calls the library. 


DONTCARE Since the state of a DONTCARE library depends on the 
mechanism chosen by the operating system for that 
particular execution of the library, Unisys recommends that - 
programs should not be written to depend on the state of a 
DONTCARE library. 


See Also 


e For more information on temporary and permanent libraries, see “TEMPORARY” 
later in this section. 


e Note that SHAREDBYRUNUNIT libraries are implemented to ensure that 
the library state conforms to ANSI-74 Inter-Program Communication (IPC) 
requirements. See Section 13, “ANSI Inter-Program Communication (IPC),” for 
more information. 
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CANCEL Statement for Libraries 
The CANCEL statement, implemented to meet the requirements of the ANSI-74 
COBOL Inter-Program Communication (IPC) module, causes the operating system 
to disassociate the specified library from the calling program and attempt to allow the 
library to end. 


The general format of this statement is as follows: 


literal-1 literal-2 


CANCEL BL { 


eri | | | 


Explanation of Format 


The CANCEL statement informs the operating system that the linkage between the 
calling program and the library is to be severed. 


The contents of the literal or the identifier used in a CANCEL statement must be a valid 
library-name (as was discussed earlier in this section). 


- _Identifier-1, identifier-2, and so on must be defined as alphanumeric data items. 


Literal-1, literal-2, and so on must be nonnumeric literals. 
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Effect of Library Initial State on a CANCEL Statement 


Because the CANCEL statement is implemented to meet the requirements of the 
ANSI-74 Inter-Program Communication (IPC) module, its operation and its effect on the 
initial state of the library depend on the value of the SHARING compiler control option 
for the library. These dependencies are described in Table 15-3. 


Table 15-3. Effect of SHARING Option Value and Library Initial State on CANCEL 
Statement — 


SHARING Option 
Value | Effect on Library Initial State 


SHAREDBYRUNUNIT The library is sent to end-of-task (EOT). The next CALL statement 

or PRIVATE : executed reinitiates the library in its initial state. Repeated execution 
of CALL and CANCEL statements to the same library is costly 
because of the overhead involved in task termination and 
reinitiation. Carelessness in the use of the CANCEL statement when 
the SHARING option is equal to SHAREDBYRUNUNIT or PRIVATE 
can lead to extremely inefficient application systems. 


SHAREDBYALL The library is not sent to EOT. Instead, the operating system issues 
an execution-time warning message stating that the library was 
delinked and not terminated. When the next CALL statement for the 
library is executed, the library is in the state it was in when it last 
executed an EXIT PROGRAM statement. Unisys suggests that the 
CANCEL statement be avoided for libraries with the SHARING 
option equal to SHAREDBYALL because of the overhead associated 
with the execution-time warning. 


DONTCARE The operating system determines the effect of the CANCEL 
statement. Because the result is unpredictable, Unisys recommends 
that the CANCEL statement be avoided for libraries with the 
SHARING option equal to DONTCARE. . 
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Library Attributes 


The following paragraphs describe the types of attributes that are valid for libraries and 
the way in which library attributes can be changed.. | . 


Types of Library Attributes 
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Libraries, like files, have attributes that can be set programmatically. The following five 
attributes are associated with libraries: 

e FUNCTIONNAME 

e INTNAME 

e LIBACCESS 

e LIBPARAMETER 

e TITLE | 


All the attributes except the LIBACCESS attribute are EBCDIC attributes of type 
STRING. a 


The LIBACCESS attribute is a mnemonic-type attribute that has two possible values: 
BYTITLE (the default) and BYFUNCTION. The effect the values of the LIBACCESS 
attribute have on the TITLE and the FUNCTIONNAME attributes are shown in 
Table 15-4. 


Table 15-4. Effects of Setting the LIBACCESS Attribute 


. LIBACCESS Attribute Value Effect , . 


BYFUNCTION Setting the LIBACCESS attribute to the value BYFUNCTION 
’ has the following effects: 


e The TITLE attribute has no effect. 


e The FUNCTIONNAME attribute is used to locate the 
appropriate code file in the operating system library 
function table. 


e Thecode file associated with the FUNCTIONNAME 
attribute is used. 


BYTITLE The TITLE attribute is used to access the code file. 


See Also 


For more information about library attributes, see the A Series System Software Utilities 


_ Operations Reference Manual. 
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CHANGE ATTRIBUTE Statement for Libraries 


Library attributes can be changed dynamically by the user program before the first 
attempt to link to the library; they cannot be changed after linkage is established. 


The CHANGE ATTRIBUTE statement is used to change library attributes. The format 
of this statement is as follows: 


CHANGE ATTRIBUTE library-attribute { \ "library-id" 


identifier 
TO ¢ literal 


mnemonic-attribute-value 


Explanation of Format 


The library-id specifies the library that has changed attributes and is the same format as 
the run-time library-id in Format 3 of the CALL statement. The identifier must be an 
alphanumeric data item with USAGE IS DISPLAY. The literal must be a nonnumeric 
literal. The mnemonic-attribute-value, used only with the LIBACCESS attribute, must 
be either BYTITLE or BYFUNCTION. 


Library attributes cannot be changed after a CALL statement is issued for the library 
unless the library has been canceled. 


If no CHANGE ATTRIBUTE statement is present, the INTNAME and TITLE 
attributes are set to the name specified by library-name in the CALL statement, and the 
LIBACCESS attribute is set to BYTITLE. The FUNCTIONNAME attribute has no 
effect on a library whose LIBACCESS attribute is set to BYTITLE. 


If a user program sets the value of the LIBACCESS attribute to BYFUNCTION, but 
does not set the value of the FUNCTIONNAME attribute before it calls the library 
program, then the user program sets the value of the FUNCTIONNAME attribute to 
the code file-name in the CALL statement. Note that the TITLE attribute has no effect 
on a library whose LIBACCESS attribute is set to BYFUNCTION. 


See Also 


For information on passing program control to a library and on terminating a library, 
refer to “Referring to a Library” earlier in this section. _ 
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Library Compiler Control Options 


The LIBRARYLOCK, SHARING, and TEMPORARY compiler control options control 
the way the library is used. 


LIBRARYLOCK 


If a library is called only by COBOL74 programs and the library is declared with the 
SHARING option equal to PRIVATE, then the LIBRARYLOCK option can remain 
FALSE. Since the library services only one user at a time, the system preserves data 
integrity without incurring the additional cost of using compiler locking code. . 


If a library is called by programs written in other languages and the library is declared 
with the SHARING option equal to PRIVATE, then the LIBRARYLOCK option should 
be set to TRUE to ensure data integrity. 


If the SHARING option.is not PRIVATE, the setting of the LIBRARYLOCK option has 
no effect on the generation of library locking code. 


See Also 


Refer to “LIBRARYLOCK” in Section 17, “Control of the Compilation Process,” for 
more information about this option. 


SHARING 
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ay 


The creator of the library specifies the allowed simultaneous uses of a library by using 
the SHARING option. Table 15-5 shows the various option values and their meanings. 


Table 15-5. Meanings of SHARING Option Values 


PRIVATE A separate instance of the library is started for each user. 


SHAREDBYALL All simultaneous users share the same instance of the 
library. 


SHAREDBYRUNUNIT All programs in the process family use the same instance of 
the library. SHAREDBYRUNUNIT is the default value. 


DONTCARE The operating system optimizes the library sharing. 


Users of a library can be restricted not only through the different library-sharing 


- specifications, but also through the normal file-access restrictions of the system. 


Only libraries with the SHARING option SHAREDBYRUNUNIT (the default value) or 
PRIVATE can be canceled. Attempts to cancel other types of libraries are completely 
ineffective and result only in a warning message. 
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See Also 


e Refer to “SHARING?” in Section 17, “Control of the Compilation Process,” for more 
information about this option. 


e For information on dissociating a library from a calling program, refer to “CAN CEL 
Statement for Libraries” earlier in this section. 


TEMPORARY 


The TEMPORARY compiler control option, in conjunction with the SHARING option, 
determines whether a library created by the COBOL compiler functions as a temporary 
or a permanent library. The effectiveness of the TEMPORARY option depends on the 
value of the SHARING option. A library can be made permanent only if the SHARING 
option has been specified as SHAREDBYALL or DONTCARE. 


A temporary library is created if the value of the TEMPORARY option is TRUE and the 
SHARING option has the value SHAREDBYALL or DONTCARE. A temporary library 
terminates if no users are referencing it. If the library is called again at a later time, a 
new copy is initiated. 


A permanent library is created if the value of the TEMPORARY option is FALSE (the 
default) and the SHARING option has the value SHAREDBYALL or DONTCARE. A 

permanent library remains in the mix with no users, and its procedures are available for 

any later programs. A permanent library is terminated only by direct operator action. 


Table 15-6 summarizes the combinations of SHARING and TEMPORARY compiler 
control options values that create temporary or permanent libraries. 


Table 15-6. SHARING and TEMPORARY Compiler Control Option Combinations 


. TEMPORARY Option 
SHARING Option Value TEMPORARY Option TRUE FALSE 


PRIVATE Temporary library Temporary library 
SHAREDBYRUNUNIT Temporary library Temporary library 
SHAREDBYALL Temporary library Permanent library 


DONTCARE Temporary library Permanent library 
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Program Samples of Referring to a Library 
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The following program samples show various ways of calling a library, canceling a library, 
and setting of library attributes. 


Example 1 | 


The first call in Example 15-1 references OBJECT/A/COBOL/LIB, the second and third 
calls reference OBJECT/ANOTHER/COBOL/LIB, and the fourth call references a 
library with the internal name LIB and the title OBJECT/SAMPLE/DYNAMICLIB. 


The fourth call enables multiple references to use LIB to reference the library. Also, 
the fourth call shows that the CHANGE ATTRIBUTE TITLE statement might prove 
useful in applications in which the library title is not known at compile time and when it 
is desirable to circumvent the performance issues and implementation constraints of the 
CALL identifier-3 statement. ; 


088198 IDENTIFICATION DIVISION. 
00620 ENVIRONMENT DIVISION. 
098306 DATA DIVISION. 

@0B49G WORKING-STORAGE SECTION. 
@0058@ G1 PARAM PIC 9(21) COMP. 
Q0G68H PROCEDURE DIVISION. 
800706 ONLY-HEADER. 


200808 CALL "PROCEDUREDIVISION OF OBJECT/A/COBOL/LIB" 
920988 USING PARAM. 

901208 CANCEL "OBJECT/A/COBOL/LIB". 

- 601188 CHANGE ATTRIBUTE TITLE OF "OBJECT/A/COBOL/LIB" TO 
001200 "OBJECT /ANOTHER/COBOL/LIB". 

901219* 

@@1220*THE FOLLOWING IS AN EXAMPLE OF AN IPC CALL. 
001230* 

901300 CALL “OBJECT/A/COBOL/LIB" USING PARAM. 

901359" 

@@136@*THE FOLLOWING IS AN EXAMPLE OF A LIBRARY CALL. 
@01370* 

201428 CALL "PROCEDUREDIVISION OF OBJECT/A/COBOL/LIB" 
881508 USING PARAM. 

001620 CHANGE ATTRIBUTE TITLE OF "LIB" TO 

201720 "QBJECT/SAMPLE/DYNAMICLIB". 

201808 CALL "ENTRYPOINTNAME IN LIB" USING PARAM. 
901920 STOP RUN. | 


Example 15-1. Calling a Library 
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Example 2 


Example 15-2 illustrates calling a library by function. Note that only libraries that 
accept parameters by reference can be used with COBOL74 programs. The example 
also illustrates access to the arithmetic function RANDOM. The example assumes that 
SYSTEM/GENERALSUPPORT has been installed as GENERALSUPPORT in the 
library function table of the operating system. 


OP2GGGIDENTIFICATION DIVISION. 

BO4GBGBENVIRONMENT DIVISION. 

— BBEBBSDATA DIVISION. 

GOB8GGBBWORKING-STORAGE SECTION. 

81909877 SEED PIC 9(11) USAGE BINARY. 

@1200877 RANDOM-RESULT USAGE REAL. 

B14GGGPROCEDURE DIVISION. 

9 1690G0NLY-PARAGRAPH. 

818988 CHANGE ATTRIBUTE LIBACCESS OF "GENERALSUPPORT" 


B28080 TO BYFUNCTION. 

B22080 CALL "RANDOM OF GENERALSUPPORT" 

B24G08 USING SEED 

826008 GIVING RANDOM-RESULT. 

026280 CHANGE ATTRIBUTE FUNCTIONNAME OF "SYNONYM1" 
826480 TO "GENERALSUPPORT". 

626608 CHANGE ATTRIBUTE LIBACCESS OF "SYNONYM1" 
026880 TO BYFUNCTION. 

027088 CALL "RANDOM OF SYNONYM1" 

827288 USING SEED 

827408 GIVING RANDOM-RESULT. 


O28G809 STOP RUN. 
Example 15-2. Calling a Library by Function 


Example 3 


Family substitution can occur when the library is linked by title. In this situation, it is 
desirable to link by function to an initialized library or to control the family substitution 
~ as shown in Example 15-3. 


@G1880*THE FOLLOWING SEQUENCE LINKS A LIBRARY TO A CODE FILE ON "DISK" 
@B15GG*WHEN FAMILY SUBSTITUTION KEEPS THE LIBRARY FROM LINKING. 
081890* 

822006 MOVE ATTRIBUTE FAMILY OF MYSELF TO SAVEFAM. 

@G400G CHANGE ATTRIBUTE FAMILY OF MYSELF TO ".". 

086900 CALL “INITIALIZE IN LIB1". | 

@@800G CHANGE ATTRIBUTE FAMILY OF MYSELF TO SAVEFAM. 


Example 15-3. Substituting a Family Specification 
See Also 


Refer to the FAMILY attribute in the A Series Task Attributes Programming Reference 
Manual for more information. 
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Section 16 
Internationalization 


Internationalization refers to the Unisys software, firmware, and hardware features that 
enable you to develop and run application systems that can be customized to meet the 
needs of a specific language, culture, or business environment. The internationalization 
features provide support for several character sets, different international business and 
cultural conventions, extensions to data communications protocols, and the ability to use 
one or more natural languages concurrently. 


This section describes the internationalization features you can use to customize an 
application for the language and conventions of a particular locality. Using these features 
to write or modify an application is termed localization. The MultiLingual System 
(MLS) environment enables you to process information to localize your applications. 
Some of the localization methods included in the MLS environment include. translating 
messages to another language, choosing a particular character set to be used for data 
processing, and defining date, time, number, and currency formats for a particular 
business application. 


In addition to the information described in this section, refer to the A Series 
MultiLingual System (MLS) Administration, Operations, and Programming Guide for 
information. The MLS Guide provides definitions for and detailed information about: 
the ccsversions, character sets, languages, and conventions provided by Unisys. It also 
describes procedures for setting system values for the internationalization features. 


The system requires a Mark 3.9 or later operating system to use many of the features 
of the MLS environment. Programs that use the internationalization features might 
not compile or run on earlier operating systems. All programs that ran on the previous 
release will continue to run. Refer to the MLS Guide for additional information about 
MLS environment installation requirements. 
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Accessing the Internationalization Features 


You can use the following two methods separately or together to access the 
internationalization features. Both of these methods are fully described later in this 
section. 


e COBOL74 provides language syntax that enables you to localize your program. For 
example, when you specify a particular ccsversion in your program, the compiler uses 
the collating sequence associated with the ccsversion for alphanumeric comparisons. 


e The system provides a system library, CENTRALSUPPORT, that contains 
procedures for localizing your program. You can access the library procedures by 
using the CALL verb. When a call occurs, input parameters describe the type of 
information that is needed or the action that is to be performed. Output parameters 
are returned with the result of the procedure call. For example, you can call the 
procedure CNV_FORMATTIME COB to format the time according to me language 
and convention that you specify. 


In your program, you must designate that you want to use the internationalization 
features; otherwise, your program will not access them. In other words, a program is not 
affected by the features described in this section unless the program specifically invokes 
them. Any programs that already exist and do not invoke internationalization features 
are not affected by the features. 


Using the Ccsversion, Language, and Convention Default Settings 
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The program can choose the specific ccsversion, language, and convention settings that 
it needs by setting the input parameters to a procedure. The system also has default | 
settings for the internationalization features at other levels. The default settings. 

can also be accessed by the program. See “Understanding the Hierarchy for Default 
Settings” later in this section for information on the available levels and on the features 
supported at each level. 


The current system default settings can be determined by using one of the following two 
methods: 


e The program calls the CENTRALSTATUS Hiseaiiees in the CENTRALSUPPORT 
library. 


e Asystem administrator, a privileged user, or a user who is allowed to use the system 
console can use MARC menus and screens or the SYSTEMOPTIONS system 
command. Refer to the MLS Guide or the A Series Menu-Assisted Resource Control 
(MARC) Operations Guide for the instructions to aepley, the default ccsversion, 
language, or convention with MARC. 


The system default settings provided by Unisys are as follows: 


Feature Default 
Ccsversion ASeriesNative 
Language English 


Convention ASeriesNative 
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Before you change the default settings for localization, you must consider consider the 
feature and the level at which the feature is defined. As an example, the ccsversion can 
be changed only at the system operations level. A program can avoid making specific 
settings by taking advantage of the default settings. For example, if the system-defined 
ccsversion is France, the language is Francais, and the convention is FranceListing, the 
program can use those default settings without coding the settings within the program. 
A program can use the default settings with the use of predefined values as input 
parameters. These parameters tell the procedure to use the current default setting. See 
“Input Parameters” later in this section for specific information on those parameters. 


To use the system default ccsversion, you must specify the CCSVERSION phrase in 
the SPECIAL-NAMES paragraph and not include the literal-1 option. The clause 
alphabet-name IS CCSVERSION identifies the collating sequence associated with the 
alphabet-name as the system default collating sequence. 


You can specify five different date or time formats by using the the TYPE clause in 


the DATA DIVISION. You can use the system default eEUaee and convention by not 
including the USING phrase of the TYPE clause. 


See Also 


e Refer to “SPECIAL-NAMES Paragraph” in Section 5, “ENVIRONMENT 
DIVISION,” for more information about the CCSVERSION phrase. 


e Refer to “TYPE” in Section 7, “DATA DIVISION,” for more information about using 
this clause for date and time editing. 


Understanding the Hierarchy for Default Settings 


The default settings for the internationalization features can be established at the 


following levels: 
Task Established at task initiation 
Program Established at compile time 
Session Handled by MARC or CANDE commands or by programs 
which support sessioning 
Usercode Established in the USERDATAFILE file 
System Established with a system or MARC command 


There is a priority associated with these levels. A setting at the task level overrides a 
setting at the program level. A setting at the program level overrides a setting at the 
session level. A setting at the session level overrides a usercode or system level setting 
and so on. A language and convention can be established at any level, but the ccsversion 
can be established only at the system level. 


Two task attributes enable you to change the language, the convention, or both. These 
attributes are the LANGUAGE and CONVENTION task attributes. By using these 
attributes, you have the option to select from among multiple languages and conventions 
when running a program. Information on the use of task attributes is provided in the 

A Series Task Attributes Programming Reference Manual. 
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The LANGUAGE task attribute establishes the language used by a program at run time. 


The CONVENTION task attribute establishes the convention used by a program at 
run time. For example, an international bank might have a program to print bank 


' statements for customers in different countries. This program could have a general 


routine to format dates, times, currency, and numerics according to the selected 
conventions. To print a bank statement for a French customer, this program could 
set the CONVENTION task attribute to FranceBureautique and process the general 
routine. For a customer in Sweden, the program could set the CONVENTION task 
attribute to Sweden and process the general routine. 


As you code your program you can use the defaults in both the source code and the calls 
to the CENTRALSUPPORT library, or you can use the settings of your choice. The task 
level and system level are probably the most useful levels for your program. Because the 
language and convention features have task attributes defined, you can access or set 
these task attributes in your program. | 


Understanding the Components of the MLS 
Environment 


Understanding Coded Character Sets and Ccsversions 
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The following four components of the MLS environment support different languages and 
cultures: 


e Coded character sets 
e Ccsversions 
e Languages 


e Conventions 


The following paragraphs describe the function of each of these components. 


A coded character set is a set of rules that establishes a character set and the one-to-one 
relationship between the characters of the set and their code values. The same | 
character set can exist with different encodings. For example, the LATIN1-based 
character set can be encoded in an International Organization for Standardization (ISO) 
format or an EBCDIC format. Coded character sets are defined in the MLS Guide. 


A coded character set name and number is given to each unique coded character set 
definition. This name or number may also be used to set the INTMODE or EXTMODE 
file attribute value for a file. For more information on these attributes, see the File 
Attributes Reference Manual. 


A cesversion is a collection of information necessary to apply a coded character set ina 
given country, language, or line of business. This information includes the processing 
requirements such as data classes, lower-to-uppercase mapping, ordering of characters, 
and escapement rules necessary for output. A ccsversion name and number is given to 
each unique group of information. This name and number may also be used to set the 
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CCSVERSION file attribute for a file. For more information on these attributes, see the 
File Attributes Reference Manual. . 


Each A Series system includes a data file, SYSTEM/CCSFILE, containing all coded 
character sets and ccsversions that are supported on the system. You cannot choose a 
coded character set directly, but by choosing a ccsversion, you implicitly designate the 
default coded character set for your system. 


Data can be entered and manipulated in only one coded character set and ccsversion at 
atime. Although there are many ccsversions that can be accessed, there is only one 
ecsversion active for the entire system at one time. This is called the system default 
ecsversion. All coded character set and ccsversion information can be accessed by calling 
CENTRALSUPPORT library procedures. 


You can use any of the following ways to find out which coded character sets and 
cesversions are available on the system: 


e Look inthe MLS Guide. Your system might have a subset of the ones defined in 
that guide. 


e Use the MARC menus and screens or the system command SYSTEMOPTIONS. 
Refer to the MLS Guide or the System Commands Operations Reference Manual. 


e Calli the CCSVSN NAMES NUM procedure. 


You might want to refer to the MLS Guide for a complete understanding of ccsversions 
and the relationship of a coded character set and a ccsversion. 


~ You must use language syntax to establish that a cesversion is to be used in your 
program. To do this, specify a PROGRAM COLLATING SEQUENCE clause and an 
alphabet-name is CCSVERSION literal-1 clause in the ENVIRONMENT DIVISION. 


You can enter and manipulate data in any one particular coded character set and 
ccsversion. Although there are many ccsversions that can be accessed, there is only one 
cesversion active for the entire system at one time. This is called the system default 
ecsversion. You can select a ccsversion to be used during the execution of your program. 
by including the literal-1 option in the CCSVERSION clause. If you do not use the 
literal-1 option, the program uses the system default ccsversion. 


Many of the procedures require the specification of a coded character set or ccsversion as 
an input parameter. A program can choose a specific coded character set or ccsversion 
by calling the procedure using the name or number of the coded character set or the 
ccsversion as an input parameter. A program can also use the system default setting 

by using predefined values as input parameters. See “Input Parameters” later in this 
section. - 


It is possible to use a different ccsversion in your program by changing the value of 
the literal-1 option. For example, by changing the value of literal-1, your program 
could process data in the ASeriesNative ccsversion and then process data in the Swiss 
cesversion. 
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See Also 


For Hoke information about the CCSVERSION clause, see “SPECIAL-NAMES 
Paragraph,” in Section 5, “ENVIRONMENT DIVISION.” 


Understanding Mapping Tables 


A mapping table is used to map one group of characters to another group of characters 
or another representation of the original characters. Many CENTRALSUPPORT 
library procedures store coded character set and ccsversion information in ALGOL-type 
translate tables as a way of defining, processing, and mapping data. For example, a 
translate table can exist to translate lowercase characters to uppercase characters. It 
is not necessary to understand the layout of an ALGOL-type translate table because 
the table is usually not visible to your program. A description of translate tables is 
provided in the A Series ALGOL Programming Reference Manual, Volume 1: Basic 


_ Implementation. 


The internationalization procedures provide you with access to mapping tables that 


_ apply to data specified in coded character sets or to specified cesversions. These mapping 


tables are as follows: 


e Mapping data from one coded character set to another coded character set 
e Mapping data from lowercase to uppercase characters 
e Mapping data from uppercase to lowercase characters 


e Mapping data from alternative numeric digits defined in a ccsversion to numeric 
digits in U.S. EBCDIC 


e Mapping data from numeric . digits i in U.S. EBCDIC to alternative numeric digits 
defined in a ccsversion 


e Mapping characters to their escapement values 


You must use procedures from the CENTRALSUPPORT library to access these 

mapping tables or to process data using these tables. For example, you can use the 
CCSTOCCS_TRANS TEXT procedure to translate data from one coded character set to 
another coded character set. You can use the VSNTRANS TEXT procedure for the rest - 
of the mapping tables. 


See the MLS Guide for definitions of mapping tables for each coded character set and 
ecsversion. 


Understanding Data Classes 
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A data class is a group of characters sharing common attributes such as alphabetic, upon 
which membership tests can be made. Some characters might not have a data class 
assigned to them. Many CENTRALSUPPORT library procedures store ccsversion 
information in ALGOL-type truthset tables as a way to define ccsversion data classes. A 
truthset is a method of storing the declared set of characters that defines a data class in 
ALGOL. It is not necessary to understand the layout of an ALGOL-type translate table 
because the table is usually not visible to your program. A description of translate tables 
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is provided in the A Series ALGOL Programming Reference Manual, Volume 1: Basic 
Implementation. 


The internationalization features provide you with access to additional truthsets that 
apply to a ccsversion. These truthsets are as follows: 


e Cesversion alphabetic 
e Ccsversion numeric 

e Ccsversion graphics 

e Ccsversion spaces 

e Cesversion lowercase 


e Ccsversion uppercase 


The alphabetic truthset contains those characters that are considered to be alphabetic 
for a specified ccsversion; the numeric truthset contains those characters that are 
considered to be numeric for a specified ccsversion, and so on. 


The compiler automatically accesses the alphabetic truthset if you have specified a 
PROGRAM COLLATING SEQUENCE clause and an alphabet-name IS CCSVERSION 
literal-1 clause in the ENVIRONMENT DIVISION. Then if you use the identifier IS 
ALPHABETIC clause, the compiler makes the class condition test sensitive to the 
cesversion alphabetic data class. 


You can use procedures from the CENTRALSUPPORT library to access these truthsets 
or to process data using these truthsets. For example, if a program manipulates 

an employee identification number such as 555962364, it might then need to verify 

that the text is or is not all numeric. The program can call the VSNINSPECT_ TEXT 
CENTRALSUPPORT library procedure to compare the text to the numeric truthset. 
This procedure returns the information that the text is or is not all numeric. 


See Also 


Refer to the MLS Guide for definitions of ccsversions and data classes. 


Understanding Text Comparisons 


You might need to perform a text comparison to sort and merge text, to compare 
relationships between two pieces of text, or to index a file. 


The traditional method for handling text comparisons is based on a strict binary 

comparison of the character values. The binary method of comparison is not meaningful 
_ when used for sorting text if the binary ordering of the coded characters does not 

match the ordering sequence of the alphabet. This situation is the case for most coded 

character sets. 


Because the binary method is not sufficient for all usage requirements, Unisys supports 
the definitions of two other levels of ordering. 
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The first level is called ORDERING. For this level, each character has an ordering 
sequence value (OSV). An OSV is an integer in the range 0 (zero) through 255 that is 
assigned to each code position in a character set. The OSV indicates a relative ordering 
value of a character. An OSV of 0 (zero) indicates that the character comes before a 
character with an OSV equal to 1. More than one character can be assigned the same 
OSV. 


The second level is called COLLATING. For this level, each character has an OSV and 

a priority sequence value (PSV). A PSV is an integer in the range 1 through 15 that is 
assigned to each code position in a character set. A PSV indicates a relative priority 
value within each OSV. Each character with a unique OSV has a PSV equal to 1, but two 
characters with the same OSV have different PSVs to separate them. 


When comparing two strings of data, we call a comparison that uses only 1 level, the 
Ordering level, an equivalent comparison. A comparison that uses both levels, Ordering 


and Collating, is called a logical comparison. 


You can specify the following three types of comparisons by calling procedures in the 


CENTRALSUPPORT library: 
Ordering Type Explanation 
Binary Compares two records based on the hexadecimal code 
values of the characters. . | 
Equivalent Compare two records based on the OSVs of the characters. 
This type of comparison uses the ORDERING level. 
Logical - Compares two records based on the OSVs plus the PSVs of 


‘the characters. This type of comparison uses the 
COLLATING level. 


In addition to the three types of ordering, Unisys also supports the following two types of 
character substitution: 


Substitution Explanation 


Many to One A predetermined string of up to three characters can be 
ordered as if it were one character, assigning it a single OSV 
and PSV pair. Even if a character is part of a predetermined 
string of characters that are ordered as a single value, the 
character still has an OSV and a PSV pair assigned to it to 
allow for cases in which the character appears in other 
strings or individually. For example, in Spanish, the letter 
pair ch is ordered as if it were a single letter, different from 
either c or h, and ordering between c and d. 


One to Many A single character can generate a string of two or three OSV 
and PSV pairs. For example, the 6 (the German sharp S) 
character is ordered as though it were ss. 


You can specify a collating sequence to be used for text comparisons. When you 
designate an internationalized collating sequence at the program level and you are 
comparing two alphanumeric records, the compiler uses the logical ordering type when 
generating the text comparison routines. 


16-8 | 8600 0296-000 


Internationalization 


Historically, text was sorted by using a standard system-provided method that is based 
on a strict binary comparison of the character values. Within a program, you might also 
specify a collating sequence to be used for text comparisons. 


Your program can call the CENTRALSUPPORT library procedures listed in Table 16-1 
under the category "Comparing and Sorting Text" to obtain ordering information of the 
cesversion, and to sort or compare text based on this information. 


See Also 


Refer to Volume 2 for information about using an equivalent string comparison among 
entities of a SIM data base and ordering localized data retrieved from a SIM data base. 


Sorting and Merging 


Because of the complexity of the SORT and MERGE statements, and because the 
compiler generates the sort compare procedure to be used in the sort and merge 
operations, you can specify a localized collating sequence to be used at the program level, 
or at the SORT or MERGE statement level. To use this language syntax, specify an 
alphabet-name IS CCSVERSION option in the SPECIAL-NAMES paragraph. Then if 
you specify a localized collating sequence at the program level, the compiler generates 
the text comparison routines. | 


Creating Indexed Files 


If you are creating a localized indexed file, you must use the KEY-LENGTH and 
~ COMPARISON phrases of the SELECT clause to specify the key value and the type of 
comparison to be done. 


The KEY-LENGTH phrase specifies the number of 8-bit characters the system uses to 
store a translated key value. Translated display data can require a larger storage area 
when including ordering and collating information. The KEY-LENGTH phrase can be 

used with the prime record key or the alternate record key. 


The COMPARISON phrase specifies the type of comparison to be performed when 
searching for the key. A binary, logical, or equivalent comparison can be specified. 


You must use the same ccesversion when you create the file and when you use it. A 


run-time error occurs when you open an indexed file for output if the run-time ccsversion 
does not match the compile-time ccsversion. 


See Also 


Refer to “FILE-CONTROL Paragraph” in Section 5, “ENVIRONMENT DIVISION,” for 
the syntax of the COMPARISON and KEY-LENGTH phrases. 
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Providing Support for Natural Languages 


The natural language feature enables users of your application program to communicate 
with the computer system in their natural language. A natural language is a human 
language in contrast to a computer programming language. 


You must write your COBOL74 program in the subset of the standard EBCDIC 
character set defined by the COBOL language. Only the contents of string literals, data 
items with variable character data, or comments can be in a character set other than 


that subset. 


If your program interacts with a user, has a user interface with screens or forms, displays 
messages or accepts user input, then those aspects of the program should be inthe __ 
natural language of the user. For example, French would be the natural language of a 
person from France. 


Refer to the MLS Guide for a list of user interfaces that can be localized. The following 
text explains how to develop a COBOL application program which supports interaction 
in the natural language of the user. 


Creating Messages for an Application Program 
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In the MLS environment, the messages handled by your application program are 
grouped into the following categories: _ 


Message 

Category Explanation 

Output message A message that an application program displays to the user. Some 
examples of output messages are error messages and prompts for input. 
An output message can be localized so that it can be displayed in the 
language of the user. 

Input message A message received by an interactive program either from a user or from 


another program in response to a prompt for input. The input message 
might be in a language that the program cannot recognize. In this case, 
the message must be translated so that it can be understood by the 
program. : 


If you develop input and output messages within an output message array, you make 

the localization process easier. When messages are in an output message array, the 
translator can use the MSGTRANS utility to localize the messages into one or more 
natural languages. The MSGTRANS utility finds all output message arrays ina program 
and presents them for translation. If messages are not in output message arrays, a 
translator must search the source file for each message and then translate the message. 


You can create an output message array by creating an ALGOL library that contains 
OUTPUTMESSAGE ARRAY declarations. _ 


An output message array contains output messages to be used by the MultiLingual 


System (MLS). ALGOL statements within the output message array declaration contain 
output messages or translate input messages. You can then call the library from your 
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application program. The MLS Guide describes the procedures for creating and using 
- output message arrays. 


There is a program on the release media that demonstrates how to create 
an ALGOL library containing output message arrays. The program is called 
EXAMPLE/MLS/ALGOL/LIBRARY. 


See Also 


For information on how to call an ALGOL library from a COBOL74 program, refer to 
Section 15, “Libraries.” 


Creating Multilingual Messages for Translation 
The following are guidelines for creating messages that can be multilingual: 


e Put all output messages in output message arrays. 


e Allow more space for translated messages. Because the English language is more 
compact than many other natural languages, a message in English generally becomes 
about 33 percent longer after it is translated into another language. For example, if 
a program can display an 80-character message, an English message should be only 
60 characters long so that the translated message can expand by one-third and not 
exceed the maximum display size. 


e Accept or display any messages through a library interface similar to that provided 
on the release media. 


e Use complete sentences for messages because phrases are difficult to translate 
accurately. 


e Do not use abbreviations because they are difficult to translate. 


Providing Support for Business and Cultural Conventions 


The business and cultural features enable users of an application program to display — 
and receive data according to local conventions. A convention consists of formatting 
instructions for date, time, numeric, currency, and page size. 


Unisys provides standard convention definitions for many formatting styles. For 
example, some of the conventions are Denmark, Italy, Turkey, and UnitedKingdom1. 
These convention definitions contain information to create formats for time, date, 
numbers, currency, and page size required by a particular locality. 
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Each A Series system includes a data file named SYSTEM/CONVENTIONS that 
contains all the convention definitions supported on the system. Although you can 
access many conventions, only one convention is active at a time for the entire system. 
This convention is called the system default convention. You can access conventions as 
follows: 


e Look inthe MLS Guide. Your system might have a subset of the ones defined in 
that guide. 


‘e Use the MARC menus and screens or the system command SYSTEMOPTIONS. | 


Refer to the MLS Guide or the System Commands Operations Reference Manual. 


e Call the CNV_NAMES procedure to ia a the names of conventions available on 
the host computer. 


If none of the conventions provided by Unisys meet your needs, you can define a new 
convention. You must use a template to define a convention. A template is a group of 
predefined control characters that describe the components for date, time, numeric, or 
currency. For example the data item 02251990 and the template !0o!/!dd!/!yyyy! produce 
the formatted date, 02/25/1990. To use some of the CENTRALSUPPORT library 
procedures, you must understand how templates are defined. The MLS Guide describes 
how to define a template. 


Using the Date and Time Features 


COBOL74 provides several date and time features for standard use. You can access the 
conventions either by using language syntax or by calling a CENTRALSUPPORT sas 
procedure. 


Formatting Date and Time with Syntax Elements 
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COBOL?74 provides the eee language syntax to handle formatting of date and time 
data items: 


e You can declare a data item to have one of several date or time types in the TYPE 
clause of the data-description entry. You can also designate a language or convention 
with the TYPE clause. 


e¢ COBOL74 provides special registers, date and time editing, and PROCEDURE 
DIVISION statements for standard formatting of date and time. These standard 
features include the following: 


- The special registers TODAYS-DATE, DATE, and DAY satis the system date 
with MMDDYY, YYMMDD, and YYDDD formats respectively. 


— The special register TIME provides the elapsed time after midnight on a 24-hour 
clock, in the format HHMMSSTT, where HH equals hours, MM equals minutes, 
SS equals seconds, and TT equals hundredths of a second. For example, 12:01 
p.m. is expressed as 12010000. 


~ The special register TIMER provides the number of 2. 4-microsecond intervals 
since midnight. 
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- The special register TODAYS-NAME provides the name of the current day of 


the week. 


- You can specify the date punctuation (space, slash, or hyphen), the time 
punctuation (colon or space), and the thousand separator (comma or space) in 
the PICTURE clause. For example, 


65 DATE-YYMMDD 
@5 DATE-MMDDYY 
@5 DATE-YYDDD 
85 TIME-HHMMSS 
@5 AMOUNT 


PIC 99/99/99 
PIC 99-99-99 
PIC 998999 

PIC 99:99:99 
PIC 99B999.99 


- The COBOL74 compiler provides date and time editing with conventions, with 
the particular convention and language specified as a property of the receiving 
-data item. The MOVE statement causes the editing to occur. 


- The ACCEPT statement transfers the formatted system date or time into the 
data item specified by the identifier using the TYPE, CONVENTION, and 
LANGUAGE declared for the item. 


See Also 


e Refer to “Special Registers” in Section 2, “Language Elements,” for details about 


the special registers. 


e Refer to “Editing” in Section 6, “Data COCED IS; ” for information about editing with 


the PICTURE clause. 


Formatting Date and Time with Library Calls 


You can call the CENTRALSUPPORT library procedures to format your date and time 
items. The following types of procedures are available to format the date and time: 


Procedure Type 


Convention 


Template 


System 
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Description 


You supply the convention name and the value for the date 
or time. The procedure returns the date or time value in the 
format used by the convention. All the conventions are — 
described in the MLS Guide. 


You supply the following: the format that you want for the 
date or time in a template parameter; the value for the date 
or time. You must use predefined control characters to 
create the template. These control characters are described 
in the MLS Guide. 


The system supplies the date and time. There is a procedure 
that formats the system date, the system time, or both 
according to a convention and a procedure that formats the 
system date, the system time, or both according to a 
template that you supply. ; 
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Example 


You could use the CNV_SYSTEMDATETIME COB procedure to display the system 
date and time according to the language and convention you choose. If you designate the 
ASeriesNative convention and the ENGLISH language, the date and time are displayed 
as follows: 


9:25 AM Monday, July 4, 1988 


If you designate the FranceListing convention and the French language, the same date 
and time might be displayed as follows: 


9h25, lundi 4 juillet 1988 


Table 16-1 lists other procedures to inquire about the conventions that are available on 
your system. 


Using the Numeric and Currency Features 


COBOL74 provides several numeric and currency features for standard use. 
You can access the conventions either by using language syntax or by calling 
a CENTRALSUPPORT library procedure. Table 16-1 provides a list of the 
CENTRALSUPPORT library features that concern numeric and currency features. 


Formatting Numerics and Currencies with Syntax Elements 


The standard COBOL74 compiler provides you with the following ways to edit currency 
and numeric displays: 


e You can specify a single character as the currency symbol. For example, in the 
SPECIAL-NAMES paragraph, the CURRENCY IS literal-9 option specifies the 
value of literal-9 as the currency symbol throughout the entire program. 


e Youcan to specify a comma as the decimal sign and a period as the thousand 
separator. In the SPECIAL-NAMES paragraph, the DECIMAL-POINT IS COMMA 
clause causes a comma to be used as the decimal sign and a period to be used as the 
thousand separator throughout the entire program. 


e By using output message arrays, your program can pass numeric values to messages 
as records of type USAGE IS DISPLAY. These records can contain numeric 
formatting, which uses a comma as the thousands separator and a period for the 
decimal sign. 


Formatting Numerics and Currencies with Library Calls 
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In addition to using the features in COBOL74, you can call the CENTRALSUPPORT 
library procedures to inquire about numeric symbols or format currency amounts. All 
numeric or currency symbols can be retrieved with a CENTRALSUPPORT library 
call. Monetary amounts in real number form can be formatted according to different 
conventions. 
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You can use the CNV_CURRENCYEDIT_COB procedure to format a monetary value 
according to the convention you choose. For example, if you designate the Greece 
convention, the monetary amount 12345.67 is formatted as follows: 


DR.12 345,67 


Using the Page Size Formatting Features 


Page sizes are specific to a locality. COBOL74 provides several standard features 
for formatting page size. You can set the number of lines per page and the number 
of characters per line by using language syntax. Alternately, you can call the 
CNV_FORMSIZE procedure to obtain predetermined page size values for the 
convention you specify. 


Formatting Page Size with Syntax Elements 


COBOL74 provides the following language syntax to handle formatting of the size of 
pages: . 


e LINAGE clause in the DATA DIVISION 
e Report Writer 
e ADVANCING phrase of the WRITE statement 


Formatting Page Size with Library Calls 


The CNV_FORMSIZE procedure enables you to retrieve default lines-per-page and 
characters-per-line values for a specified convention. 


For example, the Netherlands convention definition specifies 70 lines as the default page 
length and 82 characters as the default page width, while the Zimbabwe convention 
definition specifies 66 lines as the default page length and 182 lines as the default page 
width. 

Summary of Language Syntax by Division 


The following paragraphs describe the changes you can make in the divisions of a © 
COBOL74 program to use internationalization features. 


IDENTIFICATION DIVISION 


No changes are required in this division. 
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ENVIRONMENT DIVISION 


The language syntax that you can use in the ENVIRONMENT DIVISION includes the 
following: 


The PROGRAM COLLATING SEQUENCE IS alphabet-name clause in the 
OBJECT-COMPUTER paragraph declares that the collating sequence to be used is 
the one associated with the alphabet-name. The alphabet-name must be the same as 
the one named in the SPECIAL-NAMES paragraph. The collating sequence is used 
for alphabetic ono in conditional statements and for sorting and merging 
routines. 


The alphabet-name IS CCSVERSION literal-1 clause in the SPECIAL-NAMES 
paragraph designates the system collating sequence and the ccsversion. If you do 
not use the literal-1 option, the system uses the system default ccsversion values for 
the collating sequence and the cesversion. If you do specify literal-1, then the literal 
identifies the ccsversion. 


The following two phrases are used by KEYEDIOII to create a localized indexed 
file: 


—- The KEY-LENGTH IS literal-2 phrase of the SELECT clause specifies the 
number of 8-bit characters the system uses to store a translated key value. 
Translated display data can require extra storage area for ordering and collating 
information and for the length of the key. A run-time error occurs when the 
indexed file is created if the compile-time and run-time ccsversions are not the 
same. 


- The COMPARISON IS phrase of the SELECT clause specifies the type of 
comparison to be performed when searching for the key. 


The DECIMAL-POINT IS COMMA option of the SPECIAL-NAMES paragraph 
causes the functions of the EBCDIC comma and decimal point to be switched. 


The CURRENCY SIGN IS literal-9 clause of the SPECIAL-NAMES paragraph 
enables you to specify a single character to be used as the currency symbol in 
numeric data. 


_DATA DIVISION 
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The language syntax that you can use in the DATA DIVISION includes the following: . 


The TYPE option of the data-description entry for record structures allows a data 
item to be declared to be one of the following date or time types: 


— LONG-DATE 

- SHORT-DATE 
— NUMERIC-DATE 
—~ LONG-TIME 

- NUMERIC-TIME 


The USING phrase of the TYPE option allows the data item to be formatted 
according to a designated language or convention. 
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The KANJI phrase of the USAGE clause enables you to display and write messages 
in Japanese and other natural languages that require the double-octet format. 


Standard COBOL74 editing also can be used to format date and time. 


PROCEDURE DIVISION | 


The language syntax that you can use in the PROCEDURE DIVISION includes the 
following: 


The identifier IS ALPHABETIC clause tests whether an identifier is in the 
alphabetic truthset. If you have specified a ccsversion in the ENVIRONMENT 
DIVISION, the system determines the alphabetic truthset with respect to the 
alphabetic data class of the ccsversion. 


The ACCEPT identifier statement transfers a formatted system date or time to the 
identifier. The format of the system date or time data item depends on the coding of 
the TYPE, LANGUAGE, and CONVENTION clauses for the item. 


The MOVE statement causes a receiving item with an associated TYPE clause to 
be formatted according to the TYPE, LANGUAGE, and CONVENTION clauses 
declared for the item. If no LANGUAGE and CONVENTION clauses are specified, 
the compiler uses the hierarchy to determine the language and convention to be 
used. 


If the receiving item is of type SHORT-DATE, LONG-DATE, or NUMERIC-DATE, 
the sending item must of of format YYYYMMDD where YYYY represents the year, 
with a value in the range 0000 through 9999; MM represents the month, with a 
value in the range 01 through 12; and DD represents the day, with a value in the 
range 01 through 31. 


If the receiving item is of type LONG-TIME or NUMERIC-TIMB, the sending item 
must be of format HHMMSSPPPP where HH represents the hour, with a value in 
the range 00 through 23; MM represents the minutes, with a value in the range 00 
through 59; SS represents the seconds, with a value in the range 00 through 59; and 
PPPP represents the partial seconds, with a value in the range 0000 through 9999. 


The CALL statement can be used to call the procedures of the CENTRALSUPPORT 
library. | 

The SORT and MERGE statements use the collating sequence of a specified 
ccsversion if you establish a program collating sequence in the ENVIRONMENT 


DIVISION and do not override it in the COLLATING SEQUENCE IS 
alphabet-name option in the SORT or MERGE statement. 


The CHANGE ATTRIBUTE LIBACCESS statement can be used to change a library 


call by function to a library call by title or vice-versa. 
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Example 


Example 16~1 shows the five different types of date and time items and their expected 
values upon execution of the ACCEPT statement. The PICTURE size of the data-items 
depends on the definition of the type defined in the conventions file provided by Unisys. 


DATA DIVISION. 


WO 
G1 
G1 
G1 
G1 
61 


*. 


RKING-STORAGE SECTION. 
LONG-DATE-ITEM PIC 
SHORT-DATE-ITEM PIC 
NUM-DATE-ITEM PIC 
LONG-TIME-ITEM PIC 
NUM-TIME-ITEM PIC 


PROCEDURE DIVISION. 


+ + + € F F 


X (38) 
X(9) 
X (8) 
X (28) 
X (28) 


TYPE IS LONG-DATE. 
TYPE IS SHORT-DATE. 
TYPE IS NUMERIC-DATE. 
TYPE IS LONG-TIME. 
TYPE IS NUMERIC-TIME. 


Get the system date and time in the various formats defined by the 
CONVENTION and LANGUAGE task attributes for the task. Assume a 
convention of ASERIESNATIVE and a language of ENGLISH, a current 
date of 31 August 1998, and a current time of 2:37:20 PM. 


ACCEPT LONG-DATE-ITEM FROM DATE. 


+ 


* 


The LONG-DATE-ITEM now contains Friday, August 31, 1998. 


ACCEPT SHORT-DATE-ITEM FROM DATE. 


* 


* The SHORT-DATE-ITEM now contains Fri, Aug 31, 1999. 


* 


ACCEPT NUM-DATE-ITEM FROM DATE. 


* 


* 


* 


The NUM-DATE-ITEM now contains 98/31/99. 


ACCEPT LONG-TIME-ITEM FROM TIME. 


* The LONG-TIME-ITEM now contains 14 hours 37 minutes 28 seconds. 


* 


ACCEPT NUM-TIME-ITEM FROM TIME. 


* 


* The NUM-TIME-ITEM now contains 14:37:20. 


e 


STOP RUN. 
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Example 16-2 shows the five different types of date or time items and their expected 
values upon execution of the MOVE statement. The PICTURE size of the data-items 
depends on the definition of the type defined in the conventions file provided by Unisys. 


DATA DIVISION. 


WORKING-STORAGE SECTION. 


81 LONG-DATE-ITEM 
G1 SHORT-DATE-ITEM 
G1 NUM-DATE-ITEM 
61 LONG-TIME-ITEM 
81 NUM-TIME-ITEM 


* 


PROCEDURE DIVISION. 


+ + + + F F 


PIC 
PIC 
PIC 
PIC 
PIC 


MOVE "19999831" TO LONG-DATE-ITEM. 
* 


X (38) 
X(9) 
X(8) 
X(29) 
X (28) 


TYPE IS LONG-DATE. 
TYPE IS SHORT-DATE. 
TYPE IS NUMERIC-DATE. 
TYPE IS LONG-TIME. 
TYPE IS NUMERIC-TIME. 


Convert the literal date and time into the various formats defined. 
by the CONVENTION and LANGUAGE task attributes for the task. Assume 
a convention of ASERIESNATIVE and a language of ENGLISH, a current 
date of 31 August 1998, and a current time of 2:37:28 PM. 


* The LONG-DATE-ITEM now contains Friday, August 31, 1999. 


* 


* 


MOVE "19998831" TO SHORT-DATE-ITEM. 


* The SHORT-DATE-ITEM now contains Fri, Aug 31, 1992. 
* 


MOVE "19988831" TO NUM-DATE-ITEM. 


* 
* The NUM-DATE-ITEM now contains 98/31/98. 
* 


MOVE "143728208906" TO LONG-TIME-ITEM. 


* 
* The LONG-TIME-ITEM now contains 14 hours 37 minutes 28 seconds. 
* 


* 


MOVE "143728008080" TO NUM-TIME-ITEM. 


* The NUM-TIME-ITEM now contains 14:37:29. 


STOP RUN. 


Example 16-2. Coding the MOVE Statement for Internationalization 
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See Also 


© For syntactical information about the statements used to localize an application, 
refer to the discussions of the ACCEPT, CALL, SORT, MERGE, and MOVE 
statements in Section 9 “PROCEDURE DIVISION Statements.” 


e For information about the alphabetic test, refer to “Class Condition,” in Section 8, 
“PROCEDURE DIVISION Concepts.” 


Summary of CENTRALSUPPORT Library Procedures 


The CENTRALSUPPORT library procedures are integer-valued procedures. The 
procedures return values in output parameters and as the procedure result. 


You can check the result returned by each procedure by using standard programming 
practices. The result is useful in deciding if an error has occurred. The possible values 
for each procedure result are listed in the description of each procedure. The meanings 
of the result values are described at the end of this section. 


The CENTRALSUPPORT library procedures are called by application programs and 
system software. 


Following are some of the tasks your program can perform by calling 
CENTRALSUPPORT library procedures: 
e Identify available coded characters sets and ccsversions. 
e Map data from one coded character set to another. 
e Process data according to ccsversion. 
_@ Compare and sort text. 
e Position characters. 
e Determine available natural languages. 
e Access CENTRALSUPPORT library messages. 
e Identify available conventions definitions. 
e Obtain convention information. 
e Format dates according to convention. 
e Format times according to convention. 
e Format monetary data according to convention. 
e Determine default page size. 


‘Table 16-1 lists the CENTRALSUPPORT library procedures according to the tasks the 
procedures perform. The table also describes the purpose of each procedure. 
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Table 16-1. Functional Grouping of CENTRALSUPPORT Library Procedures 


Category Procedure Name Explanation 


Identifying Available Coded Character 
Sets and Ccsversions 


CENTRALSTATUS Obtains the values of the default settings for 

. internationalization features on the host computer. This 
procedure returns the names of the default ccsversion, 
language, and convention. It also returns the number of the 
default ccsversion. 


CCSVSN_NAMES_NUMS Returns the names and numbers of all coded character sets or 
all ccsversions available on the host computer. The names 
and numbers are listed in two arrays. These arrays are 
ordered so that the names in the names array correspond to 
the numbers in the numbers array. 


VALIDATE_NAME_RETURN_NUM Verifies that a designated coded character set or ccsversion 
name is valid on the host computer. If the coded character set 
or ccsversion is valid, the procedure returns the corresponding 
number. 


VALIDATE_NUM_RETURN_NAME Verifies that the designated coded character set or ccsversion 
number is valid on the host computer. If the coded character 
set or ccsversion is valid, the procedure returns the 
corresponding name. . 


Mapping Data from One Coded 
Character Set to Another 


CCSTOCCS_TRANS_TEXT Maps data from one coded character set to another coded 
character set by using a translate table. Characters are 
translated using a one-to-one mapping between the two 
character sets. 


Processing Data According to 
Cesversion 


VSNINSPECT_TEXT Compares the input text to a designated ccsversion truthset to 
. determine whether the characters in the text are in the 
truthset. You can use this procedure to determine if 
characters are in one of the following truthsets: 


e Alphabetic 

e Numeric 

e Spaces 
Presentation 
Lowercase 


Uppercase 


continued 
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Table 16-1. Functional Grouping of CENTRALSUPPORT Library Procedures (cont.) 


Category Procedure Name Explanation 


VSNTRANS_TEXT Translates data using a designated ccsversion. 


You can use this procedure to perform the following types of 
translations: 


e@ Lowercase to uppercase characters 
e Uppercase to lowercase characters 
e The digits 0 through 9 to alternate digits 
e — Alternate digits to the digits 0 through 9 


e Characters to their character escapement directions 
Comparing and Sorting Text 


VSNCOMPARE_TXT Compares two strings using one of the following comparison 
methods for a designated ccsversion: 


e Binary comparison, which is based on the binary values 
of the characters 


Equivalent comparison, which is based on the ordering 
sequence values of characters 


Logical comparison, which is based on the ordering 
sequence values and priority sequence values of 
characters Lo 


VSNGETORDERINGFOR_ONE_TEXT Returns the ordering information for the input text. The 
. ordering information determines how the input text is collated. 
It includes the ordering and priority sequence values of the 
characters and any substitution of characters to be made 
when the input text is sorted. You can choose one of the 
following types of ordering information: 


e Equivalent ordering information, which comprises only 
the ordering sequence values 


Logical ordering information, which comprises the 
ordering sequence values followed by the priority 
sequence values. 


continued 
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Table 16-1. Functional Grouping of CENTRALSUPPORT Library Procedures (cont.) 


Category Procedure Name Explanation 
Positioning Characters 


VSNESCAPEMENT . Takes the input text and rearranges it according to the’ 
escapement rules of the ccsversion. Both the character 
advance direction and the character escapement direction are 
used. If the character advance direction is positive, then the 
start position of the text is the leftmost position of the starting 
character. If the character advance direction is negative, then 
the starting position for the text is the rightmost position of the 
last character. From that point on, the character advance 
direction value and the character escapement direction 

' values, in combination, control where each character should 
be placed in relation to the previous character. 


Determining Available Natural 
Languages 


MCPBOUND_LANGUAGES Returns the names of the languages that are currently bound 
to the MCP. 


Accessing CENTRALSUPPORT Library 
Messages 


GET_CS_MSG Returns text of the message associated with the designated 
CENTRALSUPPORT error number. Your program can specify 
the maximum message length desired. If the returned 
message is shorter, it is padded with blanks. 


An entire message consists of three parts: 


e The header, which always takes up the first 80 
characters of the return message 


The general description, which takes the next 80 
characters 


The specific description, which has no maximum length 


Identifying Available Convention 
Definitions 


CENTRALSTATUS Obtains the values of the default settings for 
internationalization features on the host computer. This 
procedure returns the names of the default ccsversion, 
language, and convention. It also returns the number of the 
default ccsversion. 


CNV_NAMES Returns the names of the conventions available on the host 
system. 


CNV_VALIDATENAME Returns a value. that indicates whether the specified 
convention name is currently defined on the host system. 


continued 
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Table 16-1. Functional Grouping of CENTRALSUPPORT Library Procedures (cont.) 


Category Procedure Name Explanation 


Obtaining Convention Information 


CNV_SYMBOLS Returns the numeric and monetary symbols defined for a 
designated convention. The symbols in the convention are _ 


e Numeric positive symbol 

e@ Numeric negative symbol 

e Numeric thousands separator symbol 

e Numeric decimal symbol 

e Numeric left enclosure symbol 

e Numeric right enclosure symbol 
Numeric grouping 
Monetary positive symbol 
Monetary negative symbol 
International currency notation 
National currency symbol 
Monetary grouping 
Monetary thousands separator symbol 
Monetary left enclosure symbol 

e Monetary right enclosure symbol 

e Monetary decimal symbol 


CNV_TEMPLATE_COB Returns the requested template for a designated convention. 
You can obtain the template for the following: 


e Long date format 

e Short date format 

e Numeric date format 

e Long time format 
Numeric time format 
Monetary format 


Numeric format 


continued 


oat 
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Table 16-1. Functional Grouping of CENTRALSUPPORT Library Procedures (cont.) 


Category Procedure Name Explanation 


Formatting Dates According to 
Convention 


CNV_DISPLAYMODEL._COB Returns either the date or time display model defined for the 
designated convention. The components of the model are 
translated to the designated language. 


CNV_FORMATDATE_COB Formats a numeric date that has the form YYYYMMDD. The 
numeric date is passed as a parameter to the procedure 
according to a designated convention and language. The date 
can be formatted using the long, short, or numeric date format 
defined in the convention. 


CNV_FORMATDATETIMETMP_COB Returns the system date, the time, or both in the designated 
language, formatted according to a template passed to this 
procedure. 


CNV_SYSTEMDATETIMETMP_COB Returns the system date, the time, or both, formatted 
according to the designated convention template and 


language. You can choose from the following types of formats: 


e Long date and long time 

e Long date and numeric time 

e Short date and long time 

e Short date and numeric time 
Numeric date and long time 
Numeric date and numeric time 
Long date only 
Short date only 

e Long time only 

e Numeric time only 


FORMATDATETMP_COB Formats a numeric date passed as a parameter to the 
procedure according to a template and language passed as 
parameters of the procedure. 


continued 
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Table 16-1. Functional Grouping of CENTRALSUPPORT Library Procedures (cont.) 


Category Procedure Name Explanation 


Formatting Times According to 
Convention 


CNV_DISPLAYMODEL_ COB .Returns either the date or time display model defined for the 
designated convention. The components of the model are 
translated to the designated language. 


CNV_FORMATTIME_COB Formats a time with the form HHMMSSPPPP. The time is 
passed as a parameter to the procedure according to a 
designated convention and language. The time can be 
formatted using the long or numeric time format defined in the 
convention. 


CNV_FORMATTIMETMP_COB Formats a time passed as a parameter to the procedure 
according to a template and language passed as parameters 
of the procedure. 


CNV_SYSTEMDATETIMETMP_COB Returns the system date, the time, or both in the designated 


language, formatted according to a template passed to this 
procedure. 


CNV_SYSTEMDATETIME_COB Returns the system date, the time, or both, formatted 
according to the designated convention template and 
language. You can choose from the following types of formats: 


e Long date and long time 

e Long date and numeric time 

e Short date and long time 
Short date and numeric time 
Numeric date and long time 
Numeric date and numeric time 
Long date only 
Short date only 
Long time only 


Numeric time only 


continued 
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Table 16-1. Functional Grouping of CENTRALSUPPORT Library Procedures (cont.) | 


Category Procedure Name Explanation 


Formatting Monetary Data According to 
Convention 


CNV_CURRENCYEDIT_ COB Formats a monetary value passed as a parameter to the 
procedure according to the monetary editing format template 
defined in the designated convention. 


CNV_CURRENCYEDITTMP_COB Formats a monetary value, passed as a parameter to the 
procedure, according to a template also passed as a 
parameter. The template is retrieved from the 
CNV_TEMPLATE procedure. 


Determining Default Page Size 


CNV_FORMSIZE Returns the default lines-per-page and characters-per-line 
values defined in a designated convention for formatting 
printer output. 


Library Calls 


You can access the procedures in the CENTRALSUPPORT library by following these 
steps: 


1. Declare the parameters of the library procedure in the WORKING-STORAGE 
SECTION of the program. — 


2. Use the CHANGE statement syntax to specify the value of the LIBACCESS library 
attribute as BYFUNCTION. 


3. Use the CALL statement syntax to call a library procedure where the library 
identity is procedure-name of CENTRALSUPPORT, the parameters are listed in 
the USING clause, and the procedure result is specified in the GIVING clause. | 

An example of the declarations and the syntax necessary to call the 


CENTRALSUPPORT library is aie in the description of each procedure later in 
this section. 


“See Also 


For general information about calling library procedures, refer to Section 15, “Libraries.” 


Parameter Categories 


. All integer parameters are passed by reference rather than by value. The 
CENTRALSUPPORT library procedures return output parameters and procedure 
result values. The parameter types are further described on the following pages. 
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Input Parameters. 


In many cases, one of the input parameters requires that you supply the ccsversion name 
or number, the language name, or the convention name. You can obtain this information 
in the following ways: 


_@ The MLS Guide describes all the possible ccsversions, languages, and conventions 


that Unisys provides. However, your system might have only a subset of the ones 
provided. There may also be customized conventions that are not listed in the MLS 
Guide. These may be identified by the next two options. 


e Ifyou are a system administrator, a privileged user, or are allowed to use the system 
console, you can use MARC menus and screens, or the SYSOPS command to list the 
options that exist on your system. The MLS Guide provides the instructions needed 
to obtain information about ccsversion, language, or convention defaults on your 
system. 


e You can call procedures in the CENTRALSUPPORT library that will return the 
default ccsversion, language, and convention on the system. If you are writing 
an application to be used on another system, you might want to use these library 
procedures to verify that the ccsversion, the HanEUPES; or the convention specified by 
the user is valid on that system. 


The fields of parameters that you supply as 01-level records have fixed positions. This 
means that you must use blanks or zeros in any fields that you omit. 


For any procedure which accepts a ccsversion number as an input parameter, you can 
specify a —2 as input to indicate that the system default value should be used. For any 
procedure that accepts a cesversionname as an input parameter, you can specify all 
blanks or all zeros as inputs to indicate that the system default value should be used. 

For any procedure that accepts a language or convention name as an input parameter, 
you can specify all blanks or all zeros as inputs to indicate that the task attribute should 
be used. If the task attribute is not available, the CENTRALSUPPORT library searches 
down the hierarchy until a usable value is found. 


input Parameters with Type Values 
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Many of the CENTRALSUPPORT procedures have an input parameter that indicates 
the type of information to be applied or returned in the procedure. The values in these 
parameters are referred to as type values. The values used in the convention (CNV) 
procedures are common across all CNV procedures. The values used in the coded 
character set and ccsversion (VSN) procedures are common across all CCS and VSN 
procedures. 


For example, there is a parameter used in some procedures that specifies the formatting 
of the time. In the examples, the parameter is named CS-NTIMEV. You must choose a 
type value to indicate a format. For example, a value of 3 indicates the long time format 
is used. 
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Because the parameters are passed by reference, you need to declare and assign the type 
values in the WORKING-STORAGE SECTION. You can then use a MOVE statement to 
move the value into the parameter as shown in the following example: 


MOVE LONG-TIME-V TO CS-NTIMEV. 


Example 
Example 16-3 shows a sample set of WORKING-STORAGE declarations for the 
parameters that have type values. The procedures are explained later in this section 
using the type value names declared in this example. Notice that numeric items must 
be declared PIC $9(11) USAGE BINARY. This declaration is required for parameter 


matching to type INTEGER. 


77 
ae 
77 
77 
77 
77 
77 
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CS-BINARYV — 
CS-EQUIVALENTV 
CS-LOGICALV 
CS-CHARACTER-SETV 
CS-CCSVERSTONV 
CS-NUMTOALTDIGV 
CS-ALTDIGTONUMV 
CS-LOWTOUPCASEV 
CS-UPTOLOWCASEV 
CS-ESCMENTPERCHARV 
CS-ALPHAV 
CS-NUMERICV 
CS-PRESENTATIONV 
CS-SPACESV 
CS-LOWERCASEV 
CS-UPPERCASEV 
CS-NOTINTSETV 
CS-INTSETV 
CS-CMPLSSV 
CS-CMPLEQV 
CS-CMPEQLV 
CS-CMPGTRV 
CS-CMPGEQV 
CS-CMPNEQV 
CS-LDATE-V 
CS-SDATE-V 
CS-NDATEV 
CS-LTIMEV 
CS-NTIMEV 
CS-LDATELTIMEV 
CS-LDATENTIMEV 
CS-SDATELTIMEV 
CS-SDATENTIMEV 
CS-NDATELTIMEV 
CS-NDATENTIMEV 
CS-LONGDATE-TEMPV 
CS-SHORTDATE-TEMPV 


PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 


$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 


$9(11) - 


$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 


USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 


BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 
BINARY 


VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 


VALUE . 


VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 


@. 


1. 
2. 
Oo. 
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items 
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77 ~CS=NUMDATE-TEMPV PIC $9(11) USAGE BINARY VALUE 


2. 
77 ~=CS=LONGTIME-TEMPV PIC $9(11) USAGE BINARY VALUE 3. 
77 CS-NUMTIME-TEMPV PIC S9(11) USAGE BINARY VALUE 4. 
77 CS=-MONETARY-TEMPV PIC $9(11) USAGE BINARY VALUE 5. 
77 ~=CS-NUMERIC-TEMPV PIC $9(11) USAGE BINARY VALUE 6. 
77. CS-DATE-DISPLAYMODEL PIC $9(11) USAGE BINARY VALUE @. 
77, CS-TIME-DISPLAYMODEL PIC $9(11) USAGE BINARY VALUE 1. 


Example 16-3. Sample Data Declarations for Type Value Data Items (cont.) 


Output Parameters 


These parameters contain the output values produced by the procedure. For example, 
the translated text produced by the procedure CCSTOCCS TRANS TEXT is returned 
in an output parameter. 


Result Parameter 


All the library procedures return an integer value as the procedure result that indicates 
whether an error occurred during the execution of the procedure. In general, a 
returned value of 1 means that no error occurred and any other value means that an 
error occurred. However, the CNV_VALIDATENAME and VSNCOMPARE TEXT 
procedures are exceptions to this rule. For these procedures, the returned value can be 
0 (zero), 1, or another value. A returned value of 0 (zero) means that no error occurred 
and the condition is FALSE. A returned value of 1 means that no error occurred and the 
condition is TRUE. Any other value means that an error occurred. 


Each procedure lists the values that can be returned by that procedure. The meanings 
of these values are explained at the end of this section. You can use these values to call 
the GET_CS_MSG procedure and display the error that occurred, or you can code error 
routines to handle the possible errors. 


See Also 


Refer to the explanation of the GET_CS MSG procedure later in this section for more 
information about using that procedure. 


Procedure Descriptions 
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The following pages describe the internationalization procedures accessible from a 
COBOL74 program. The procedures reside in the CENTRALSUPPORT library. 


Each description includes a general overview of the procedure, an example showing how 
to call the procedure, and an explanation of the parameters used in the example. Not all 


‘parameters used to produce the output will be displayed in the output. 


You can define the name of a parameter to be whatever name you want. In the following 
discussions, the parameters are given names in the example, and are identified in the 
explanation by that name. 
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The following parameters are used in many of the procedures: 


e CS-DATAOKV isa constant with a value of 1 that is compared with the RESULT 
parameter. This value indicates that the CENTRALSUPPORT library did not find 
errors and was able to process the information. 


e CS-FALSEV is a constant with a value of 0 that is compared with the RESULT 
parameter. This value indicates that although the CENTRALSUPPORT library did 
not find errors, it did not process the information. 


e SUB represents a subscript. 


CCSTOCCS TRANS TEXT 


This procedure translates data from the coded character set specified in the first 
parameter to the coded character set specified in the next parameter. Characters are 
translated using a one-to-one mapping between two coded character sets. For example, - 
you might want to translate data in the LATIN1IEBCDIC coded character set to the 
LATIN1ISO coded character set. 


Although there are many coded character set numbers, there is not a mapping table 
between every combination of coded character sets. The procedure returns an error 
indicating the data was not found if you pass two valid coded character set numbers for a 
table that does not exist. 


Refer to the MLS Guide for a list of the coded character set to coded character set 
translate tables that are defined. 


Example 


Example 16-4 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CCSTOCCS_TRANS TEXT library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC $9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example takes the cpt string ‘ scathidlo* which is encoded in the LatinLEBCDIC 
coded character set and translates it to the Latin1ISO coded character set. The string 
“pafiuelo” is represented by the following hexadecimal codes in Latin1EBCDIC: 
978149A44859396. In Latin1ISO, the hexadecimal codes are 83969586519985958385. 

You can use the MLS Guide to determine that the coded character set number for 
Latin1EBCDIC is 12 and Latin1ISO is 13. You can also retrieve these numbers by calling 
the procedure VALIDATE NAME RETURN_NUM with the coded character set names. 


_ IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


Example 16-4. Calling the CCSTOCCS TRANS TEXT Procedure 
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DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE | 
LABEL RECORD IS STANDARD | 
VALUE OF TITLE IS "OUT/COBOL74/CCSTOCCSTRANSTEXT." 
PROTECTION SAVE 
RECORD CONTAINS 8% CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


G1 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


01 OF-1. 
@5 FILLER PIC X(@9) VALUE "RESULT = ", 
95 OF-RESULT PIC 222222222229. 
@5 FILLER PIC X(59) VALUE SPACE. 

O1 OF-2. | 
@5 FILLER PIC X(12) VALUE "DEST-TEXT = ". 
@5 OF-DEST-TEXT PIC X(1@). 
@5 FILLER PIC X(58) | VALUE SPACE. 


KEEKKKKEKRKEEKRREEKERKREERREEERERERREEKEEEKERREREERREREEREREREEREREKER 


*** The following global declarations are used as parameters *** 


*** to the CENTRALSUPPORT procedures. aes 
KRAEKEKEKEKEEREEERKKEERKERREEREKRERKEEERERERRERERERRRERRAEERERERERER a 
81 DEST-TEXT PIC X(1@). 

81 SOURCE-TEXT PIC X(1). 

77. CCS-NUM-FROM PIC $9(11) USAGE BINARY. 

77 CCS-NUM-TO PIC $9(11) USAGE BINARY. 

77, CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 

77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE &. 

77, DEST-START PIC $9(11) USAGE BINARY. 

77, RESULT PIC $9(11) USAGE BINARY. 

77 SOURCE-START PIC $9(11) USAGE BINARY. 

77, TRANS-LEN _ PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CCSTOCCS-TRANS-TEXT. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


kKkRKK CCSTOCSS-TRANS-TEXT KEREKEKKEEKEEKEEKEEEKKREEREREKREEERERERER 


CCSTOCCS-TRANS-TEXT. . 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE 12 TO CCS-NUM-FROM. 


Example 16-4. Calling the CCSTOCCS TRANS TEXT Procedure (cont.) 
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MOVE 13 TO CCS-NUM-TO. 
MOVE "pafuelo" TO SOURCE-TEXT. 
MOVE 18 TO TRANS-LEN. 
CALL "CCSTOCCS TRANS TEXT OF CENTRALSUPPORT" 
USING CCS-NUM-FROM, 
CCS-NUM-TO, 
SOURCE-TEXT, 
_ SOURCE-START, 
DEST-TEXT, 
DEST-START, 
TRANS-LEN 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE DEST-TEXT TO OF-DEST-TEXT 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-4. Calling the CCSTOCCS TRANS TEXT Procedure (cont.) 


Explanation 


CCS-NUM-FROM is an integer passed to the procedure. It contains the number of the 
coded character set that you are formatting from. 


CCS-NUM-TO is an integer passed to the procedure. It contains the number of the 
coded character set you are translating the text to. The destination text will be in this 
coded character set. 


SOURCE-TEXT is passed to the procedure. It contains the text to translate. You 
specify the size of this record. 


SOURCE-START is passed to the procedure. It contains the byte offset, relative to 0 
(zero), in SOURCE-TEXT where the translation starts. 


DEST-TEXT is returned by the procedure. It contains the translated text. The size of 
this record and the record in the SOURCE-TEXT parameter should be the same. 


DEST-START is passed to the procedure. It contains the byte offset (0 relative) in the 
DEST parameter where the translated text is to be placed. 


TRANS-LEN is passed to the procedure. It specifies the number of characters in 
SOURCE-TEXT to be translated, beginning at SOURCE-START. 


RESULT is returned as the integer value of the procedure. It indicates whether an 
error occurred during the execution of the procedure. Values greater than or equal to 
1000 indicate an error. An explanation of the error result values can be found at the end 
of this section. You should check the procedure result whenever you use this procedure. 
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Possible values returned by CCSTOCCS_TRANS_ TEXT are as follows: 


1 1002 3003 
1000 3000 4002 
1001 7 3001 


Sample output from Example 16-4 follows: 


RESULT = 1 
DEST-TEXT = pafuelo 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CCSVSN_NAMES NUMS 


This procedure returns a list of the coded character set names and numbers or a list 

of the ccsversion names and numbers that are available on your system. You specify 
which list you want with the first parameter to the procedure. The names and numbers 
are listed in two arrays. These arrays are coded so that the names in the names array 
correspond to the numbers in the numbers array. 


You might use this procedure to create a menu that lists the ccsversions from which a 
user can choose. You might also use this procedure to verify that the ccsversion to Pe 
used by your program is available on the host computer. 


Example 


Example 16-5 shows the parameter deieesdons and the PROCEDURE DIVISION 
syntax required to call the CCSVSN_NAMES NUMS library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC $9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example returns a list of available ccsversion names and numbers on a system. This 
is an arbitrary list of cesversions and might not be the same on every system. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 


FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
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VALUE OF TITLE IS "OUT/COBOL74/CCSVSNNAMESNUMS., " 
PROTECTION SAVE 

RECORD CONTAINS 8@ CHARACTERS 

DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


O1 OF-1. 
@5 FILLER PIC X(@9) VALUE "RESULT = ". 
95 OF-RESULT PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(59) VALUE SPACE. 
@1 OF-2. 
05 FILLER PIC X(15): VALUE "CCSversion Name". 
@5 FILLER PIC X(@5) VALUE SPACE. 
95 FILLER PIC X(17) VALUE "CCSversion Number". 
@5 FILLER PIC X(43) VALUE SPACE. 
@1 OF-3. . 
@5 FILLER PIC X(15) VALUE ALL "-". 
95 FILLER PIC X(@5) VALUE SPACE. 
95 FILLER PIC X(17) VALUE ALL "-". 
@5 FILLER PIC X(43) VALUE SPACE. 
G1 OF-4, 
@5 OF-NAMES-ELEM PIC X(17). 
@5 FILLER PIC X(@8) VALUE SPACE. 
@5 OF-NUMS-ELEM PIC ZZZZZZZZZ2ZZ9. 
@5 FILLER PIC X(43) VALUE SPACE. 


KREKKKREKRRKKKEKREREREREREEEEREKERKEEERERERREREKEEREREREKKEKRKEKREKREKEE 


*** The following global declarations are used as parameters *** 
*** to the CENTRALSUPPORT procedures. ais 


KRKEEKEKKEKRKEKEKREREKEERRERKRERREKRKEEREEREREREREREREKRERKEKEKRREKREEEEERE 


@1 NAMES-ARY. 


85 NAMES-ELEM PIC X(17) OCCURS 2@ TIMES. 
91 NUMS-ARY USAGE BINARY. 
65 NUMS-ELEM PIC $9(11) OCCURS 20 TIMES. 
81 SUB . PIC 9(02). | 
77 ~=CS=-CCSVERSIONV PIC $9(11) USAGE BINARY VALUE 1. 
77 CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 ~CS-FALSEV PIC $9(11) USAGE BINARY VALUE &. 
77 RESULT PIC $9(11) USAGE BINARY. “ 
77 ~=TOTAL PIC $9(11) USAGE BINARY. . 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CCSVSNNAMESNUMS. 
CLOSE OUTPUT-FILE. 


Example 16-5. Calling the CCSVSN_ NAMES NUMS Procedure (cont.) 
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STOP RUN. 


KkKKK CCSVSNNAMESNUMS KKEEKKERKEKEKKEEKKEEKREREERKEEERERREEKEREKERREAEREE 


~ CCSVSNNAMESNUMS.. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
CALL "CCSVSN_NAMES NUMS OF CENTRALSUPPORT" 
USING CS-CCSVERSIONV, 
TOTAL, | 
NAMES-~ARY , 
NUMS~ARY . 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE SPACE TO OUTPUT-RECORD 
WRITE OUTPUT-RECORD 
WRITE OUTPUT-RECORD FROM OF-2 
WRITE OUTPUT-RECORD FROM OF-3 
MOVE 1 TO SUB | 
PERFORM DISPLAYARY UNTIL SUB IS GREATER THAN TOTAL. 


*xkk** DISPLAYARY FOIE IIT III Ia ith eick kee bh bk 
DISPLAYARY. 
MOVE NAMES-ELEM(SUB) TO OF=NAMES-ELEM. 
MOVE NUMS-ELEM(SUB) TO OF-NUMS-ELEM. 
WRITE OUTPUT-RECORD FROM OF-4. 
ADD 1 TO SUB. 


Example 16-5. Calling the CCSVSN_NAMES_NUMS Procedure (cont.) 


Explanation 


CS-CCSVERSIONV is passed to the procedure. It enables you to specify either of the 
following two types of information to be returned in the output parameters: 


Value Value Name Meaning 
@) CS-CHARACTER-SET-V Return the names and numbers of the coded 
character sets 
1 CS-CCSVERSION-V Return the names and numbers of the ccsversions 


TOTAL is returned by the procedure. It contains the number of coded character set or 
eesversion entries that exist. . . 


-NAMES-ARY is returned by the procedure. Each entry contains the name of a coded 


character set or ccsversion defined in the file SYSTEM/CCSFILE provided by Unisys. 
Each name uses one element of NAMES-ARY and is 17 characters long. In this example, 


up to 20 names can be stored in the record. The MLS Guide also lists all the coded 


character sets and ccsversions. The recommended array size is 340 characters. 


NUMS-ARY is returned by the procedure. NUMS-ARY contains all the coded | 
character set or ccsversion numbers defined on the host. Each number uses one 
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element of NUMS-ARY. Each element in NUMS-ARY corresponds to a parallel entry in 
NAMES-ARY and corresponds to a 17-character name. The record can hold up to 20 
numbers. The MLS Guide also provides all the numbers for the coded character sets 
and ccsversions. ; 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred in the CCSVSN_ NAMES NUMS procedure. Values greater than or equal to 
1000 indicate an error. An explanation of the error result values can be found at the end 
of this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CCSVSN_NAMES_NUMS are as follows: 

1 1002 3001 


1001 3000 . 3006 


Sample output from Example 16-5 follows: 


RESULT = eT 1 

CCSversion Name CCSversion Number 
ASERIESNATIVE 4) 
SWISS _ 2 64 
SWEDISHI1 99 
SPANISH 98 
CANADAEBCDIC 74 
CANADAGP 75 
FRANCE 35 
NORWAY 71 

See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CENTRALSTATUS 


This procedure returns the name and number of the system default ccsversion, the name 
of the system default language, and the name of the system default convention. 


You might use this procedure to provide a means for your application users to inquire 
about the default settings on the host computer. 


Example 


Example 16-6 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CENTRALSTATUS library procedure. The declarations 
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identify the category of data-item required for parameter matching. For example, 
numeric items must be declared PIC $9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 


appropriate for your use. 


This example returns the current values for the system default ccsversion, language, and 
convention. These are arbitrary system values and might not be the same on every 


system. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 


FILE-CONTROL. 


SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 


FD OUTPUT-FILE 


LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "OUT/COBOL74/CENTRALSTATUS." 


PROTECTION SAVE 


RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OQUTPUT-RECORD. 


81 OUTPUT-RECORD 


WORKING-STORAGE SECTION. 


G1 OF-1. 


5 


@5 OF-RESULT 


5 


FILLER 


FILLER 


G1 OF-2. 


5 
@5 


FILLER 
FILLER 


G1 OF-3. 


a )) 
5 


FILLER 
FILLER 


O1 OF-4. 


95 
5 
5 
5 
5 
5 


FILLER 
FILLER 
FILLER 
FILLER 


FILLER . 


FILLER 


G1 OF-5. 


G5 
95 
95 
85 
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FILLER 
FILLER 
FILLER 
FILLER 


PIC X(89). 

PIC X(@9) VALUE 
PIC ZZZZZZ2ZZ229. 
PIC X(59) VALUE 
PIC X(15) VALUE 
PIC X(65) VALUE 
PIC X(15) VALUE 
PIC X(65) VALUE 
PIC X(13) VALUE 
PIC X(29) VALUE 
PIC X(@8) VALUE 
PIC X(@8) VALUE 
PIC X(@5) VALUE 
PIC X(14) VALUE 
PIC X(13) VALUE 
PIC X(29) VALUE 
PIC X(@8) VALUE 
PIC X(@8) VALUE 


"RESULT = ". 
SPACE. 


"System Defaults”. 
SPACE. 


ALL non ry 
SPACE. 


"Field Meaning". 
SPACE. 
"Location". 
SPACE. 

"Value". 

SPACE. 


ALL a: 
SPACE. 
ALL ow. 
SPACE. 


Example 16-6. Calling the CENTRALSTATUS Procedure 
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@5 FILLER PIC X(@5) VALUE ALL "-". 
95 FILLER PIC X(14) VALUE SPACE. 
G1 ODF-1. 
5 FILLER PIC X(11) VALUE "CCSVersion:". 
@5 FILLER PIC X(@7) VALUE SPACE. 
@5 D1-SYS-ELEM PIC X(17). 
95 FILLER PIC X(45) VALUE SPACE. 
$1 DF-2. 
05 FILLER ~ PIC X(11) VALUE “Language: ". 
@5 FILLER ~ PIC X(@7) VALUE SPACE. 
@5 D2-SYS-ELEM —_—~PIC X(117).. 
@5 FILLER PIC X(45) VALUE SPACE. 
G1 DF-3. | 
@5 FILLER PIC X(11) VALUE "Convention:". 
@5 FILLER PIC X(@7) VALUE SPACE. 
@5 0D3-SYS-ELEM PIC X(17). 
95 FILLER ~ PIC X(45) VALUE SPACE. 
@1 DF-4. 
@5 FILLER PIC X(39) 
VALUE "System Default CCSVersion Number: ae 
95 FILLER PIC X(@6) VALUE SPACE. 
@5 FILLER PIC X(@3) VALUE "(1)". 
95 FILLER PIC X(@3) VALUE SPACE. 
@5 D4-CONTROL-ELEM PIC ZZZZZZZZZZZ9. 
5 FILLER PIC X(17) VALUE SPACE. 


KEKKEKEKEEKEKEEEKKEERKEKEKREKREREKEREEEEEEKERERERERERERERREREERERERERE 


*** The following global declarations are used as parameters *** 


*** to the CENTRALSUPPORT procedures. saiiad 
HHAKAKKREREKREKKRERKEKEKKEEKKEKERERKRER EER EEEREREREERERERERERERERERE 
81 CONTROL-INFO USAGE BINARY. 
85 CONTROL-ELEM PIC $9(11) OCCURS 8 TIMES. 
81 SUB PIC 9(@2). 
81 SYS-INFO. 
85 SYS-ELEM PIC X(17) OCCURS 3 TIMES. 
77 CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 


77 RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CENTRALSTATUS. 
CLOSE OUTPUT-FILE. 
STOP RUN. . 


KkRKK CENTRALSTATUS KKEEKKKEKKKKEKKEREKREEREKEKKEERRRERERERREERREEERERE | 


CENTRALSTATUS. | 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 


Example 16-6. Calling the CENTRALSTATUS Procedure (cont.) 
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CALL "CENTRALSTATUS OF CENTRALSUPPORT" 
USING SYS-INFO, 
CONTROL-INFO 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF~1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE SPACE TO OUTPUT-RECORD 
WRITE OUTPUT-RECORD 
WRITE OUTPUT-RECORD FROM OF-2 
WRITE OUTPUT-RECORD FROM OF-3 
. MOVE 1 TO SUB 
PERFORM DISPLAYSYSTEMINFO UNTIL SUB IS GREATER THAN 3 
MOVE SPACE TO OUTPUT-RECORD 
WRITE OUTPUT-RECORD 
WRITE OUTPUT-RECORD FROM OF-4 
WRITE OUTPUT-RECORD FROM OF-5 
MOVE 1 TO SUB 
PERFORM DISPLAYCONTROLINFO UNTIL SUB IS GREATER THAN 8. 


kkkeKK DISPLAYSYSTEMINFO HHKKKHAKKEKRK EKER RRA REE ERERERERREERERERERE 


DISPLAYSYSTEMINFO. 
IF SUB IS EQUAL TO 1 
THEN MOVE SYS-ELEM(SUB) TO D1-SYS-ELEM 
WRITE OUTPUT-RECORD FROM DF-1. 
IF SUB IS EQUAL T0.2 
THEN MOVE SYS-ELEM(SUB) TO D2-SYS-ELEM 
WRITE OUTPUT-RECORD FROM DF-2. 
IF SUB IS EQUAL TO 3 
THEN MOVE SYS~ELEM(SUB) TO D3-SYS-ELEM 
WRITE OUTPUT-RECORD FROM DF-3. 
ADD 1 TO SUB. 


KRKKK DISPLAYCONTROLINFO KEKKKEKREKKKEREKKEKEKEERERREREERREKRERREKKKKEKE 


DISPLAYCONTROLINFO. 
IF SUB IS EQUAL TO 1 
THEN MOVE CONTROL-ELEM(SUB) TO D4-CONTROL-ELEM 
WRITE OUTPUT-RECORD FROM DF-4. 
ADD 1 TO SUB. 


Example 16-6. Calling the CENTRALSTATUS Procedure (cont.) 


Explanation | 


SYS-INFO is returned by the procedure. Unisys recommends that the size of the record 
be 51 characters. It contains three items, each 17 characters long, in the following order: 


1. System default ccsversion name 
2. System default language name 


3. System default convention name 
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Each name is 17 characters long. Names shorter than 17 characters are padded on the 


right with blanks. 
-CONTROL-INFO is returned by the procedure. It is eight words long and contains the 
following information. 
Location Information 
Word [0] System default ccsversion number 
Word [1] through [7] Reserved | 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CENTRALSTATUS are as follows: 


1 1002 3001 
1001 3000 


Sample output from Example 16-6 follows: 


RESULT = 1 


System Defaults 


CCSVersion: ASERIESNATIVE 

Language: ENGLISH 

Convention: ASERIESNATIVE 

Field Meaning Location Value 

System Default CCSVersion Number: (1) | g 
See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CNV_CURRENCYEDITTMP_COB 


This procedure receives a real number and formats it to represent a currency value 
according to the template specified. The template may be retrieved for any convention 
from the CNV_TEMPLATE COB procedure or may be created by the user. CE-ARY 

- contains the formatted currency value... 


‘The MLS Guide describes the symbols used to create a template. 


Example 


Example 16-7 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_CURRENCYEDITTMP_COB library procedure. The 
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Internationalization 


declarations identify the category of data-item required for parameter matching. For — 
example, numeric items must be declared PIC $9(11) USAGE BINARY. _ 


In the explanation following the example, the parameters are explained using the names 
_given to them in the example. In your program, choose parameter names that are 


appropriate for your use. 


_ This example converts a real number and edits in numeric symbols that are passed in as 
a monetary template. The currency symbol is retrieved from the monetary template in 
the ASeriesNative convention and edited into the EBCDIC string. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 


SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 


FD OUTPUT-FILE | 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "QUT/COBOL74/CNVCUREDITTMPCOB. " 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 
G1 OUTPUT-RECORD PIC X(8@). 
WORKING-STORAGE SECTION. 
G1 OF-1. 
@5 FILLER PIC X(69) VALUE "RESULT 
@5 OF-RESULT PIC ZZZZZ2Z22729. 
@5 FILLER PIC X(59) | VALUE SPACE. 
G1 OF-2. . 
@5 FILLER PIC X(@9) | VALUE "CE-ARY 
@5 OF-CE-ARY PIC X(38). 
@5 FILLER PIC X(41) | VALUE SPACE. 


KKEKKKKKKEKREKREKEREKERKEREREKEREKREEREKKERRERERERERERERREKRRERERERRREERE 


*** The following global declarations are used as parameters 
to the CENTRALSUPPORT procedures. 


kkeK 


dik 
kkk 


HREKKEKKKKEKKEKRKEKEKREREKEREKKREEKREEREREKRERERKEEKRKEERKEREREREREREREEREERE 


CE-ARY 
CNV-NAME 
TMP-ARY 


AMT 
CS-DATAOKV 
CS-FALSEV 
RESULT 


PIC X(30). 
PIC X(17). 
PIC X(48). 


“REAL. 


PIC $9(11) 
PIC $9(11) 
PIC $9(11) 


USAGE BINARY 
USAGE BINARY 
USAGE BINARY. 


VALUE 1. 
VALUE 9. 


Example 16-7. Calling the CNV_CURRENCYEDITTMP_COB Procedure 


16-42 
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PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-CURRENCYEDITTMP-COB. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


KKREKK CNV -CU RRENCY EDITTMP-COB reerer Cerrar cater eececertececercert 


CNV-CURRENCYEDITTMP-COB. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE 12345.67 TO AMT. 
MOVE "ASERIESNATIVE": TO CNV-NAME. 
MOVE "ICN[-]T[,:@,3]D[.]#!" TO TMP-ARY. 
CALL "CNV_CURRENCYEDITTMP COB OF CENTRALSUPPORT" 
USING AMT, 
TMP-ARY , 
CNV-NAME, 
CE-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE CE-ARY TO OF-CE-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-7. Calling the CNV_CURRENCYEDITTMP_COB Procedure (cont.) 


Explanation 


AMT is a real number passed to the procedure. It contains the monetary value to be 
formatted. . 


TMP-ARY is passed to the procedure. It contains the formatting template used to 
format the monetary value. The recommended size of a template is 48 characters. 


CNV-NAME is an EBCDIC array passed to the procedure. It contains the name of 
the convention to be used. When a caller-supplied monetary template (in TMP-ARY) 
contains one or more control characters in simple form (that is, one or more characters 
without a symbol definition enclosed in square brackets ([]) following the character or 
characters), symbols associated with those control characters are retrieved from the 
monetary template in the convention specified by CNV-NAME. 


CE-ARY is returned by the procedure. It contains the formatted monetary value. 
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RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_CURRENCYEDITTMP COB are as follows: 


1 | 3000 
1001 3002 
1002 


Sample output from Example 16-7 follows: 


RESULT 
CE-ARY 


1 
$12,345.67 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CNV_CURRENCYEDIT_COB 


16-44 


This procedure receives a monetary value and converts it to a formatted monetary value. 
The procedure uses the monetary template of the convention you specify to accomplish 
the formatting. 


The MLS Guide describes all the conventions and the type of currency formatting 
associated with each convention. 


You might want to print a report with the numeric and currency formats for the 
CostaRica conventions (for example, CRC 89.99), or for the Norway conventions (for 
example, NKR 89.99). 


Example 


Example 16-8 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_CURRENCYEDIT_COB library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example converts a real number and edits monetary symbols from the Denmark 
convention into an EBCDIC string. 
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IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT QUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT~FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "OUT/COBOL74/CNVCUREDITCOB." 
PROTECTION SAVE 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


G1 OUTPUT-RECORD PIC X(88). 


WORKING-STORAGE SECTION. 


@1 OF-1. 
@5 FILLER PIC X(@9) VALUE "RESULT = ". 
@5 OF-RESULT PIC 2ZZZZ2Z2Z2729. 
@5 FILLER PIC X(59) | VALUE SPACE. 

@1 OF-2. : 
@5 FILLER PIC X(@9) VALUE "CE-ARY = ". 
@5 OF-CE-ARY PIC X(30). 
@5 FILLER - PIC X(41) ~~ VALUE SPACE. 


KKKEKKKEKEKEKEEREKEREKRKREKEKRREKERERRREEEKRREKEREREERERERERERERERRREEREREKRKKE 


*x* The following global declarations are used as parameters *** 


*** to the CENTRALSUPPORT procedures. staid 
HREKKKKEKEKKEKRKEKKEKERREKEKKEKREREKEKEEEEKRREREREREREKEKEEREKEKREKERERRRER 
G1 CE-ARY PIC X(30). 

@1 CNV-NAME PIC X(17). 

77 AMT REAL. 

77 CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 

77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 

77 RESULT PIC S$9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-CURRENCYEDIT-COB. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


KKK CNV-CURRENCYEDIT-COB HHKAKKREK KIRKE ERIK IRR IAERIRERERR IR 


CNV-CURRENCYEDIT-COB. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 


Example 16-8. Calling the CNV_CURRENCYEDIT_COB Procedure 
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MOVE 12345.67 TO AMT. 
MOVE "Denmark" TO CNV~NAME. 
CALL "CNV_CURRENCYEDIT_COB OF CENTRALSUPPORT" | 
USING AMT, 
CNV-NAME, 
CE-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE CE-ARY TO OF-CE-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-8. Calling the CNV_CURRENCYEDIT_COB Procedure (cont.) 


Explanation 


AMT is a real number passed to the procedure. It contains the monetary value to be 
formatted. | 


CNV-NAME is passed to the procedure. It contains the name of the convention to be 
used to format the monetary value. If this parameter contains all blanks or zeros, the 
procedure will use the hierarchy to determine the convention to be used. Refer to the 
MLS Guide for the list of convention names and the explanation of the hierarchy. 


CE-ARY is returned by the procedure. It contains the formatted monetary value. The 
recommended size of the formatted amount is 20 characters. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_CURRENCYEDIT_COB are as follows: 


1 2002 
1001 | 3000 
1002 3002 


Sample output from Example 16-8 follows: 


RESULT 
CE-ARY 


1 
Kr.12 345,67 


See Also — 


For more information on the error result values, see Table 16-2 later in this section. 
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CNV_DISPLAYMODEL COB 


This procedure returns either a numeric date or numeric time display model. A display 
model is a format that you can display to the user to show the form of the requested 
input. For example, YYDDMM is a display model that shows a user that the date must 
be entered in that form. The procedure creates the display model according to the 
convention and language that you specify. 


Example 


Example 16-9 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CVV_DISPLAYMODEL_COB library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose Pans names that are 
appropriate for your use. 


This example obtains a date display model from the ASeriesNative convention. The 
display model is translated to English and returned in DM-ARY. ~ 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
_ INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "QUT/COBOL74/CNVDSPMODELCOB. " 
PROTECTION SAVE 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8). 


WORKING-STORAGE SECTION. 


91 OF-1. 
05 FILLER PIC X(@9) VALUE "RESULT = " 
95  OF-RESULT PIC ZZZZZZZZZZ2Z9. 
@5 FILLER PIC X(59) VALUE SPACE. 

G1 OF-2. 
95 FILLER PIC X(@9) VALUE "DM-ARY = " 
@5 OF-DM-ARY PIC X(18). 
95 FILLER _ PIC X(61) VALUE SPACE. 


Example 16-9. Calling the CNV_DISPLAYMODEL_COB Procedure 
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KIKI RK IIIA IAI IIIS ISIAH AAI EAI IAAI IA EAAAS AIS 


**x The following global declarations are used as parameters *** 
*** to the CENTRALSUPPORT procedures. ree 


KEKKKKRKKERKREREREREREREREREEREREEREREREREREREREREERERERERERERERERREEK 


@1 CNV-NAME PIC X(17). 
G1 DM-ARY PIC X(10). 
G1 LANG-NAME PIC X(17). 
77 CS=DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 CS-DATE-DISPLAYMODEL PIC $9(11) USAGE BINARY VALUE @. 
77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 


77 RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-DISPLAYMODEL-COB. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


KKKKK CNV-DISPLAYMODEL-COB KKKEKKKEKEEEKREEKREREREREREREREREEREREEEERE 


CNV-DISPLAYMODEL-COB. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "ASERIESNATIVE" TO CNV-NAME. 
MOVE "ENGLISH" TO LANG-NAME. 
CALL "CNV_DISPLAYMODEL_COB OF CENTRALSUPPORT" 
USING CS-DATE-DISPLAYMODEL, 
CNV-NAME, 
LANG-NAME, 
DM-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE DM-ARY TO OF-DM-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-9. Calling the CNV_DISPLAYMODEL_COB Procedure (cont.) 
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Explanation 


CS-DATE-DISPLAYMODEL is an integer passed to the procedure. It indicates whether 
you want the display model to be a numeric date or a numeric time. 


Value Sample Data Item Meaning 
0 CS-DATE- The display model will be a numeric date. 
DISPLAYMODEL 
1 CS-TIME- The display model will be a numeric time. 
DISPLAYMODEL. 


CNV-NAME is passed to the procedure. It contains the name of the convention from 
which the date or time model is retrieved If this parameter contains all blanks or zeros, 
the procedure will use the hierarchy to determine the convention to be used. Refer to 
the MLS Guide for the list of convention names and the explanation of the hierarchy. 


LANG-NAMKE is passed to the procedure. It contains the name of the language in which 
the date or time components are to be displayed. If this parameter contains all blanks 
or zeros, the procedure uses the hierarchy to determine the language to be used. Refer 
to the MLS Guide for information about determining the valid language names on your 
system and the explanation of the hierarchy. | 


DM-ARY is returned by the procedure. It contains the display model. The 
recommended size of the display model is 10 characters. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_DISPLAYMODEL COB are as follows: 


1 2001 3001 
1001 2002 3002 
1002 3000 | 3006 


Sample output from Example 16-9 follows: 


1 


RESULT 
Y = mm/dd/yyyy 


DM-AR 


See Also 


For more information on the error result values, see Table 16~2 later in this section. 
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CNV_ FORMATDATETMP_COB 


16-50 


This procedure formats a date Pier toa template. You specify the template, date 
value, and language in which the date is to be displayed. The procedure then returns 
the formatted date. The template may be retrieved for any convention from the 
CNV_TEMPLATE COB procedure or may be created by the user. | 


Example 


Example 16-10 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_FORMATDATETMP COB library procedure. The 

declarations identify the category of data-item required for parameter matching... For 
example, numeric items must be declared PIC 89(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example formats a date using a template provided by the calling program. The 
formatted date is translated to English and returned in FD-ARY. The date consists of an 
unabridged day of week name, abbreviated month name, numeric day of month, day of 
month suffix “rd,” and numeric year. 


8600 0296-000 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE~CONTROL. 
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SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 


FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "“OUT/COBOL74/CNVFMTDATETMPCOB. " 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 
81 OUTPUT-RECORD PIC X(8Q). 
WORKING-STORAGE SECTION. 
81 OF-1. 
@5 FILLER PIC X(@9) VALUE "RESULT = " 
@5 OF-RESULT PIC ZZ22ZZ2ZZ2Z7ZZZ9. 
@5 FILLER PIC X(59) VALUE SPACE. 
61 OF-2. 
@5 FILLER PIC X(@9) VALUE "FD-ARY = " 
@5 OF-FD-ARY PIC X(45). 
@5 FILLER PIC X(26) VALUE SPACE. 


KEKKKKKKEKKERRERERERKEERKEEERKKKEEKEREREEKEERERERERERERRERERERRERERKEEE 


KKK 


RK 


The following global declarations are used as parameters 
to the CENTRALSUPPORT procedures. 


*w*k* 


KKK 


KRKEKKKKKRKEKERKRREEEREREEERREKKEERERERRKEERERKRERKRERERRKREKEKERREEEREREE 


G1 
G1 
81 
G1 


DATE-ARY 
FD-ARY 
LANG-NAME 
TMP-ARY 


77 
77 
77 


CS-DATAOKV 
CS-FALSEV 
RESULT 


PROCEDURE DIVISION. 
INTLCOBOL74. 


PIC 
PIC 
PIC 
PIC 


PIC 
PIC 
PIC 


OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-FORMATDATETMP-COB. 


CLOSE OUTPUT-FILE. 
STOP RUN. 


X (@8) . 
X(45). 
X(17). 
X (48). 


$9 (11) 
$9(11) 
$9(11) 


USAGE BINARY 
USAGE BINARY 
USAGE BINARY. 


VALUE 1. 
VALUE 9. 


kkk CNV-FORMATDATETMP-COB HRKKKKKKKKRKKKERARERKEREKERERERREREREREE 


CNV-FORMATDATETMP-COB. 


Example 16-10. Calling the CNV_FORMATDATETMP_COB Procedure 


8600 0296-000 


16-51 


Internationalization — 


CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "19981083" TO DATE-ARY. 
MOVE "!IW!, !1N!. !DE!, !Y!" TO TMP-ARY. 
MOVE "ENGLISH" TO LANG-NAME. 
CALL "CNV_FORMATDATETMP_COB OF CENTRALSUPPORT" 
USING DATE-ARY, 
TMP~ARY , 
LANG-NAME , 
FD-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE FD-ARY TO OF-FD-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-10. Calling the CNV_FORMATDATETMP_COB Procedure (cont.) 


Explanation 


DATE-ARY is passed into the procedure. It contains the date to be formatted. The date 
must be in the form YYYYMMDD. The fields of the record have fixed positions. You 
must use blanks or zeros in any fields that you omit. 


TMP-ARY is passed into the procedure. It contains the template used to format the 
date. The recommended size of a template is 48 characters. The template must use the 
control characters described in the MLS Guide. 


- LANG-NAMS is passed into the procedure. It contains the name of the language to be 
used in formatting the date. If this parameter contains all blanks or zeros, the procedure 
uses the hierarchy to determine the language to be used. Refer to the MLS Guide for 
information about determining the valid language names on your system. » 


FD-ARY is returned by the procedure. It contains the formatted date. The 
recommended size of the formatted date is 45 characters. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CVV_FORMATDATETMP_COB are as follows: 


1 2003 3011 
1001 3000 | 3012 
1002 3001 | 3030 
2001 3002 
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Sample output from Example 16-10 follows: 


RESULT 
FD-ARY 


1 
Wednesday, Oct. 3rd, 1992 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CNV_FORMATDATE_COB 


This procedure receives a date and formats it in the form you select according to the 
convention and language you specify. 


You might use this procedure to output a date according to the Greek long-date format 
and Greek language, for example. 


Example 


Example 16-11 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_FORMATDATE COB library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example formats the date in numeric form using the Netherlands convention. The 
English language is specified. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS “OUT/COBOL74/CNVFMTDATECOB. " 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


Example 16-11. Calling the CNV_FORMATDATE_COB Procedure 
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G1 


G1 


OF-1. 

95 FILLER PIC X(@9) VALUE “RESULT = “. 
85 OF-RESULT PIC ZZZZZZZZZZZ9. 

95 FILLER PIC X(59) VALUE SPACE. 

OF-2. 

@5 FILLER PIC X(@9) VALUE "FD-ARY = ". 
@5 OF-FD-ARY PIC X(1@). 

@5 FILLER PIC X(61) | VALUE SPACE. 


HREKKKKREKKERREREKREREREREEKREREREREREKREKREREREREEEREREREEREKEREERREEEKE 


kkk 
kkk 


The following global declarations are used as parameters *** 
to the CENTRALSUPPORT procedures. wk 


JEU GOS OI ICICI IIIT a aaa Aa Im 


‘61 
81 
G1 
G1 


77 
77 


77, 


77 


CNV-NAME PIC X(17). 

DATE-ARY PIC X(@8). 

FD-ARY PIC X(10). 

LANG-NAME PIC X(17). 

CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 
CS-NDATEV PIC $9(11) USAGE BINARY VALUE 2. 
RESULT PIC $9(11) USAGE BINARY. 

PROCEDURE DIVISION. 
TLCOBOL74. 


IN 


kkk 


CN 
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OPEN OUTPUT OUTPUT-FILE. | 
PERFORM CNV-FORMATDATE-COB. 
CLOSE OUTPUT-FILE. 

STOP RUN. 


kk CNY- FORMATDATE- COB KEKKEKKEKKREREREKEEKREREEKREKRREEREREKREREKK 


V-FORMATDATE-COB. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "17768704" TO DATE-ARY. 
MOVE "Netherlands" TO CNV-NAME. 
MOVE "ENGLISH" TO LANG-NAME. 
CALL "CNV_FORMATDATE_COB OF CENTRALSUPPORT" 
USING CS-NDATEV, 
DATE-ARY, 
CNV-NAME, 
LANG-NAME, 
FD-ARY | 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE FD-ARY TO OF-FD-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-11. Calling the CNV_FORMATDATE_COB Procedure (cont.) 
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Explanation 


CS-NDATEV is an integer passed by reference to the procedure. It indicates which of 
the following three formats will be used to format the date: 


Value Sample Data Item Meaning 
0 LONG-DATE-V ‘Use the long date format. 
1 SHORT-DATE-V Use the short date format. 
2 NUMERIC-DATE-V Use the numeric date format. 


DATE-ARY is passed to the procedure. It contains the date to be formatted. The date 
must be in the form YYYYMMDD., left justified. The fields of the array have fixed 
positions. You must use blanks or zeros in any fields that you omit. 


CNV-NAME is passed to the procedure. It contains the name of the convention to be 
used to format the date value. If this parameter contains all blanks or 17 character 
zeros, the procedure uses the hierarchy to determine the convention to be used. Refer 
to the MLS Guide for the list of convention names and the explanation of the hierarchy. 


LANG-NAME is passed to the procedure. It contains the language to be used in 
formatting the date. If this parameter contains all blanks or 17 character zeros, the 
procedure uses the hierarchy to determine the language to be used. Refer to the MLS 
Guide for information about determining the valid language names on your system and 
the explanation of the hierarchy. 


FD-ARY is returned by the procedure. It contains the formatted date. The 
recommended length of a formatted date is 45 characters. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_FORMATDATE COB are as follows: 


1 2002 3002 

2 2003 | 3006 
1001 . 3000 3012 
2001 3001 | 


Sample output from Example 16-11 follows: 


RESULT 
FD-ARY 


1) 


4.7.76 , 


See Also 


For more information on the error result values, see Table 16—2 later in this section. 


8600 0296-000 . | 16-55 


Iinternationalization 


CNV_FORMATTIMETMP_COB 


16-56 


This procedure formats a time according to a template. You specify the template, 

time value, and language in which the time is to be displayed. The procedure then 
returns the formatted time. The template may be retrieved for any convention from the 
CNV_TEMPLATE COB procedure or may be created by the user. 


With this procedure, if the time template is !0t!:!0m!:0s!, the language is English, and the 
input time is 1255016256, the numeric time is formatted as 12:55:01. 


Example 


Example 16-12 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV FORMATTIMETMP COB library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This Seanipks formats a caller-supplied time using a template also passed in by the 
calling program. Alphabetic time components are translated to English and returned in 


FT-ARY. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "OUT/COBOL74/CNVFMTTIMETMPCOB. " 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS . 
DATA RECORD IS OUTPUT-RECORD. — 


@1 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


@1 OF-1. 
@5 FILLER PIC X(@9) VALUE “RESULT = ". 
@5 OF-RESULT PIC 222222222229. 
@5 FILLER PIC X(59) | VALUE SPACE. 

G1 OF-2. 
@5 FILLER - PIC X(13) VALUE "FT-ARY = " 
@5 OF-FT-ARY PIC X(30). 


Example 16-12. - Calling the CNV_FORMATTIMETMP_COB Procedure 
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@5 FILLER PIC X(37) VALUE SPACE. 


KEKKKKEKKKEKKKREKEKRERERKEEERERERRRERREREKEEREREREREREREKRREEREEKRERRKEKKKKR 


* . The following global declarations are used as parameters *** 


KKK 


to the CENTRALSUPPORT procedures. 


kkk 


KEEKRKKKEREKEREKERKEEKRERRERERERERERERERREKEREEREREREKERERERERRRERKEEK 


81 
61 
G1 
G1 


77 
77 
77 


FT-ARY PIC X(30). 
LANG-NAME PIC X(17). 
TIME-ARY - - PIC X(18). 
TMP-ARY PIC X(48). 
CS-DATAOKV PIC $9(11) USAGE BINARY 
CS-FALSEV ~ PIC $9(11) USAGE BINARY 


RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 


IN 


TLCOBOL74. 

OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-FORMATTIMETMP-COB. 
CLOSE OUTPUT-FILE. 

STOP RUN. 


VALUE 1. 
VALUE @. 


KEKKK CNV-FORMATTIMETMP-COB KREKKEKKERERKERRREREREREREREEKRRERREKEKEE 


CNV-FORMATT IMETMP-COB. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 


MOVE "114958" TO TIME-ARY. 
MOVE "!T! 'T! IM! HK! IS! ERI" TO TMP-ARY. 
MOVE "ENGLISH" TO LANG-NAME. 
CALL "CNV_FORMATTIMETMP_COB OF CENTRALSUPPORT" 
USING TIME-ARY, 
TMP-ARY, 
LANG-NAME , 
FT-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE FT-ARY TO OF-FT-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-12. Calling the CNV_FORMATTIMETMP_COB Procedure (cont.) 


Explanation 


TIME-ARY is passed to the procedure. You specify the time to be formatted in the form 
-HHMMSSPPPP The partial seconds field, PPPP is optional. The fields of the SEERy. have 
fixed positions. You must use blanks or zeros in any fields that you omit. 
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TMP-ARY is passed to the procedure. You specify the template to be used to format the 
time in this parameter. The recommended length of a template is 48 characters. Refer 
to the MLS Guide for information about creating a template. 


LANG-NAME is passed to the procedure. You specify the language to be used in 
formatting the time in this parameter. If this parameter contains all blanks or zeros, the 
procedure uses the hierarchy to determine the language to be used. Refer to the MLS 
Guide for information about determining the valid language names on your system and 
the explanation of the hierarchy. 


FT-ARY is returned by the procedure. It contains the time value formatted according 
to the template and language you designated. The recommended length of a formatted 
time is 45 characters. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_FORMATTIMETMP COB are as follows: 


1 2003 | 3011 
1001 3000 . 3013 
1002 3001 3030 
2001 3002 


Sample output from Example 16-12 follows: 


RESULT = 1 
FT-ARY = 11 hours 49 minutes 58 seconds 
See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CNV_FORMATTIME_COB 


16-58 


This procedure formats a user-supplied time according to the convention, language, and 
type of time that you specify. 


Example 


Example 16-138 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CVNV_FORMATTIME COB library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 


given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


8600 0296-000 


Internationalization 


This example formats the time in numeric form using the Belgium convention. The 
formatted time is returned in FT-ARY. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS “OUT/COBOL74/CNVFMTTIMECOB." 
PROTECTION SAVE 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


@1 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


@1 OF-1. | 
@5 FILLER PIC X(@9) VALUE "RESULT = ". 
@5 OF-RESULT PIC ZZ2ZZZ222729. 
@5 FILLER PIC X(59) | VALUE SPACE. 

@1 OF-2. | 
@5 FILLER PIC X(@9) VALUE "FT-ARY = " 
@5 OF-FT-ARY PIC X(30). 
@5 FILLER PIC X(41) | VALUE SPACE. 


KEKKEKKEKEKKEKEREKEEREREREKRRRKEKRREKREKRREERERERREERREREEREREREREREKKEE 


*** The following global declarations are used as parameters *** 


_ *** to the CENTRALSUPPORT procedures. cee 
HKAKKKKKEKRERKER EERE REE ERE EK KEKE KEK EKER ERE REE REREEREREREREREREERERER 
@1 CNV-NAME — PIC X(17). 
1 FT-ARY PIC X(38). 
81 LANG-NAME PIC X(17). 
@1 TIME-ARY PIC X(1@). 
77, ~CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 ~CS-FALSEV . PIC S$9(11) USAGE BINARY VALUE @. 
77 ~CS-NTIMEV PIC $9(11) USAGE BINARY VALUE 4. 
77 RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. . 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-FORMATTIME-COB. 
CLOSE OUTPUT-FILE. 


Example 16-13. Calling the CNV_FORMATTIME_COB Procedure 
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16-60 


STOP RUN. 


kKkkKKK CNV-FORMATTIME-COB Jn deckseksckskkkkksch 


CNV-FORMATTIME-COB. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "114958" TO TIME-ARY. 
MOVE "Belgium" TO CNV-NAME. 
MOVE "ENGLISH" TO LANG-NAME. 
CALL "CNV_FORMATTIME_COB OF CENTRALSUPPORT" 
USING CS-NTIMEV, 
TIME-ARY, 
CNV-NAME, 
LANG-NAME, 
FT-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE FT-ARY TO OF-FT-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-13. Calling the CNV_FORMATTIME_COB Procedure (cont.) 


Explanation 


CS-NTIMEV is passed by 1 reference to the procedure. It indicates which of the ee 
two formats will be used to edit the time: 


Value Sample Data Item _ Meaning 
3 LONG-TIME-V Use the long time format. 
4 NUMERIC-TIME-V Use the numeric time format. 


TIME-ARY is passed to the procedure. It contains the time to be formatted in the form 
HHMMSSPPPP left justified. The partial seconds field, PPPP is optional. The fields of 
the record have fixed positions. You must use blanks or zeros in any fields that you omit. 


CNV-NAME is passed to the procedure. It contains the name of the convention to be 
used to edit the time value. If this parameter contains all blanks or zeros, the procedure 
will use the hierarchy to determine the convention to be used. Refer to the MLS Guide 
for the list of convention names and the explanation of the hierarchy. 


LANG-NAME is passed into the procedure. It contains the language to be used in 
formatting the time. If this parameter contains all blanks or zeros, the procedure 


uses the hierarchy to determine the language to be used. Refer to the MLS Guide 


for information about determining the valid language names on your system and the 
explanation of the hierarchy. 


FT-ARY is returned by the procedure. It contains the formatted time value. The | 
recommended length of the formatted time is 45 characters. — 
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RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of — 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_FORMATTIME COB are as follows: 


1 2002 3002 
1001 2003 3006 
1002 3000 3011 
2001 3001 3013 


Sample output from Example 16-13 follows: 


RESULT 
FT-ARY 


1 


11:49:58 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CNV_FORMSIZE 


This procedure returns the default lines-per-page and default characters-per-line values 
from the specified convention. Each convention provides these values to be used with 
printed output. : 


Example 


Example 16-14 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_FORMSIZE library procedure. The declarations 
identify the category of data-item required for parameter matching. For example, 
numeric items must be declared PIC $9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example obtains paper dimensions (lines per page and characters per line) from the 
Denmark convention. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 


Example 16-14. Calling the CNV_FORMSIZE Procedure 
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LABEL RECORD IS STANDARD 

VALUE OF TITLE IS "OUT/COBOL74/CNVFORMSIZE." 
PROTECTION SAVE . : 

RECORD CONTAINS 88 CHARACTERS 

DATA RECORD IS OUTPUT-RECORD. 


G1 OQUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


G1 OF-1., 
@5 FILLER PIC X(22) 
VALUE "RESULT ans 
@5 OF-RESULT PIC ZZZ22ZZZZZ2ZZ9. 
®5 FILLER PIC X(46) VALUE SPACE. 
@1 OF-2. 
@5 FILLER PIC X(22) 
VALUE "Lines per Page os 
@5 OF-LPP PIC ZZZZZZZZZ2ZZ9. 
@5 FILLER ; PIC X(46) VALUE SPACE. 
@1 OF-3. 
@5 FILLER PIC X(22) 
VALUE "Characters per Line = ". 
@5 OF-CPL PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(46) VALUE SPACE. 


KKEKEKKEKERKEKREREKEKREKKEEREREREREKREEKEEEKRERRERERRERRRRRRERERRERERERER 


*** The following global declarations are used as parameters *** 


_ *** to the CENTRALSUPPORT procedures. aE 

KEKKEKKREKREKEEKRERERKREREEREREKRERERKEREREEREEREEREEREREREKEKRKRRERKEE 
81 CNV-NAME PIC X(17). 

77 CPL PIC $9(11) USAGE BINARY. 

77. CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 

77. CS-FALSEV PIC S9(11) USAGE BINARY _ VALUE @. 

77, _~LPP PIC $9(11) USAGE BINARY. 

77 RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-FORMSIZE. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


kkkKK CNV = FO RMS I Z E HRA ERIKA IAA RARER AIA AAR IAAIARERA 


CNV-FORMSIZE. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "Denmark" TO CNV-NAME. 
CALL "CNV_FORMSIZE OF CENTRALSUPPORT" 


Example 16-14. Calling the CNV_FORMSIZE Procedure (cont.) 
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USING CNV-NAME, 
LPP, 
CPL 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE SPACE TO OUTPUT-RECORD 
MOVE LPP TO OF-LPP 
WRITE OUTPUT-RECORD FROM OF-2 
MOVE CPL TO OF-CPL 
WRITE OUTPUT-RECORD FROM OF-3. 


Example 16-14. Calling the CNV_FORMSIZE Procedure (cont.) 


Explanation 


CNV-NAMKS is passed to the procedure. It contains the name of the convention to be 
used to specify the default printer form sizes. If this parameter contains all blanks or 
zeros, the procedure will use the hierarchy to determine the convention to be used. 
Refer to the MLS Guide for the list of convention names and the explanation of the 
hierarchy. 


CPL is returned by the procedure. It contains the default number of characters per line 
specified by the convention you referenced. — 


LPP is returned by the procedure. It contains the default number of lines per page 
specified by the convention you referenced. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. _ 
Possible values returned by CNV_FORMSIZE are as follows: 


1 1002 3000 
1001 2002 


Sample output from Example 16-14 follows: 
RESULT 


= 1 
Lines per Page = 78 
Characters per Line = 82 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 
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CNV_NAMES 


16-64 


This procedure returns a list of convention names and the total number of convention 
that are available on the system. The first name is the system default name. 


You might use this procedure to obtain the name of a convention to be used as input to 
another procedure. 


Example 


Example 16-15 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_NAMES library procedure. The declarations identify 
the category of data-item required for parameter matching. For example, numeric items 
must be declared PIC $9(11) USAGE BINARY. . 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example obtains the names of conventions currently available on the system. Note 


that this is an arbitrary list that may differ from system to system. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS “OUT/COBOL74/CNVNAMES. " 
PROTECTION SAVE 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS QOUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


G1 OF-1. 
@5 FILLER PIC X(@9) VALUE “RESULT = ". 
85 OF-RESULT PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(59) VALUE SPACE. 
G1 OF-2. 
@5 FILLER PIC X(16) VALUE "Convention Names". 
@5 FILLER PIC X(64) VALUE SPACE. 
$1 OF-3. . 
@5 FILLER PIC X(16) VALUE ALL "-". 
@5 FILLER PIC X(64) VALUE SPACE. 


Example 16-15. Calling the CNV_NAMES Procedure 
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G1 OF-4. 
@5 OF-NAMES-ELEM PIC X(17). 
@5 FILLER PIC X(63) 
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VALUE SPACE. 


KEKKEAKKKKEKRERKKEKKREREKEKEEKREREREREKEREREEREKKERERRRKEEEKEKERKEREEKRKEKERER 


*** The following global declarations are used as parameters *** 


*** to the CENTRALSUPPORT procedures. 


kkk 


KKEKKKEKEKEKRKERKEKEKREREKREKEREERKRRERKREEREREREERERERERERKEEKEEREKRKEKRKKRKKEK 


@1 NAMES-ARY. 
@5 NAMES-ELEM PIC X(17) 


77 ~CS=-DATAOKV PIC $9(11) 
77 ~CS-FALSEV PIC $9(11) 
77 ~=RESULT PIC $9(11) 
77 SUB PIC $9(11) 
77 ~=TOTAL PIC $9(11) 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-NAMES. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


OCCURS 45 TIMES. 


USAGE BINARY VALUE 1. 
USAGE BINARY VALUE @. 
USAGE BINARY. 
USAGE BINARY. 
USAGE BINARY. 


kkekKK CNV-NAMES KIKI HKKKKKKKEKEKEKEKKEKKKKEKKKEKEKEEKKKKREKKEKKKEKAKRKRKEE 


CNV-NAMES. 


CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 


CALL "CNV_NAMES OF CENTRALSUPPORT" 


_ USING TOTAL, 
NAMES~-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 


THEN MOVE SPACE TO OUTPUT-RECORD 


WRITE OUTPUT-RECORD 


WRITE OUTPUT-RECORD FROM OF-2 
WRITE OUTPUT-RECORD FROM OF-3 


MOVE .1 TO SUB 


PERFORM DISPLAYNAMESARY UNTIL SUB IS GREATER THAN TOTAL. 


KkKKK DISPLAYNAMESARY RHRKKKKKKERERKEEKEREKEEEEEREREEKEREREEERERERERER 


DISPLAYNAMESARY . 


MOVE NAMES-ELEM(SUB) TO OF-NAMES-ELEM. 


WRITE OUTPUT-RECORD FROM OF-4. 
ADD 1 TO SUB. 


Example 16-15. Calling the CNV_NAMES Procedure (cont.) 
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Explanation 


TOTAL is returned by the procedure. It contains the total number of conventions that 
reside on the system. 


NAMES-ARY is returned by the procedure. Each element of the record contains the 
name of a convention defined in the SYSTEM/CONVENTIONS file. Each name uses 
one element of NAMES-ARY. The record can hold up to 20 names. Each name can be up 
to 17 characters long and is left justified in the field. If there are less than 17 characters 
in the name, the field is filled on the right with blanks. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_NAMES are as follows: 


1 1001 | 3001 


Sample output from Example 16-15 follows: 


RESULT = | 


Convention Names 
ASERIESNATIVE 
Nether] ands 
Denmark 

Uni tedKingdoml 
Turkey 

Norway 

Sweden 

Greece 
FranceListing 
FranceBureauti que 
EuropeanStandard 
Belgium | 

Spain 
Switzerland 
Zimbabwe 

Italy 

Uni tedKingdom2 
KENYA 

NIGERIA 
SOUTHAFRICA 
CYRILLIC 

BRAZIL 
NEWZEALAND 
STNDYUGOSLAVIAN 
~ FRENCHCANADA 
ARGENTINA 

CHILE 
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COLOMBIA 
COSTARICA 
MEXICO 

PERU 
VENEZUELA 
AUSTRALIA 
EGYPT 
ENGLISHCANADA 
Japanl 

Japan2 


See Also 


For more information on the error result values, see Table 16—2 later in this section. 


CNV_SYMBOLS 


This procedure returns a list of numeric and monetary symbols defined for a specified 
convention. 


Example 


Example 16-16 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_SYMBOLS library procedure. The declarations identify 
the category of data-item required for parameter matching. For example, numeric items 
must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example obtains monetary and numeric symbols, monetary and numeric grouping 
specifications, and international currency notation defined for the Norway convention. 


IDENTIFICATION DIVISION. 

ENVIRONMENT DIVISION. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "OUT/COBOL74/CNVSYMBOLS." 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


@1 OUTPUT-RECORD -~ PIC X(88). 
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WORKING-STORAGE SECTION. 


G1 OF-1. _ 
@5 FILLER PIC X(@9) VALUE "RESULT = ", | 
@5 OF-RESULT — PIC ZZZZZZZZZZZ9. 
05 FILLER PIC X(59) VALUE SPACE. 
O1 OF-2. © 
@5 FILLER PIC X(13) VALUE “Field Meaning". 
@5 FILLER PIC X(22) VALUE SPACE. 
@5 FILLER PIC X(14) VALUE "Symbols Length". 
05 FILLER ~ PIC X(@3) VALUE SPACE. 
65 FILLER PIC X(18) VALUE "Convention Symbols". 
@5 FILLER PIC X(18) VALUE SPACE. 
G1 OF-3. . 
@5 FILLER PIC X(13) VALUE ALL "-", 
85 FILLER PIC X(22) VALUE SPACE. 
@5 FILLER PIC X(14) VALUE ALL "-", 
@5 FILLER PIC X(@3) VALUE SPACE. 
@5 FILLER PIC X(18) VALUE ALL "-". 
@5 FILLER PIC X(1@) VALUE SPACE. 
@1 DF-1. 
@5 FILLER PIC X(32) 
VALUE "International Currency Notation:". 
@5 FILLER PIC X(@5). VALUE SPACE. 
@5 D1-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) VALUE SPACE. 
@5 D1-SYM-ELEM PIC X(12). 
95 FILLER PIC X(16) VALUE SPACE. 
G1 DF-2. 
@5 FILLER PIC X(32) 
VALUE "National Currency Notation: ae 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D2-SYMLEN-ELEM PIC Z2222ZZZZZZ29. 
@5 FILLER PIC X(@3) | VALUE SPACE. 
@5 D2-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) | VALUE SPACE. 
@1 DF-3. 
@5 FILLER PIC X(32) 
VALUE "Monetary Thousands Separator: ". 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D3-SYMLEN-ELEM PIC 2ZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) | VALUE SPACE. 
~ 65 D3-SYM-ELEM PIC X(12). 
65 FILLER PIC X(16) | VALUE SPACE. 
@1 DF-4. | 
@5 FILLER PIC X(32) 
> VALUE "Monetary Decimal Symbol]: rs 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D4-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. 
85 FILLER PIC X(@3) | VALUE SPACE. 
@5 D4-SYM-ELEM PIC X(12). 
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G1 


91 


81 


G1 


61 


G1 
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@5 FILLER PIC X(16) VALUE SPACE. 
DF-5. 
@5 FILLER PIC X(32) 

VALUE "Monetary Positive: Symbol: ms 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D5-SYMLEN-ELEM PIC ZZZZZZZZZ2Z9. 
@5 FILLER PIC X(@3) VALUE SPACE. 
85 05-SYM-ELEM PIC X(12). 
G5 FILLER PIC X(16) VALUE SPACE. 
DF-6. 
@5 FILLER PIC X(32) 

VALUE "Monetary Negative Symbol: ig 
65 FILLER © PIC X(@5) VALUE SPACE. 
@5 D6-SYMLEN-ELEM PIC ZZZ2ZZZZZZZZ9. 
@5 FILLER PIC X(@3) VALUE SPACE. 
85 D6-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) VALUE SPACE. 
DF-7. 
@5 FILLER . PIC X(32) 

VALUE "Monetary Left Enclosure Symbol: ". 
@5 FILLER PIC X(@5) VALUE SPACE. 


@5 D7-SYMLEN-ELEM 


PIC ZZZZZZZZZZZ9. . 


Internationalization | 


@5 FILLER PIC X(@3) VALUE SPACE. 
85 0D7-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) VALUE SPACE. 
DF-8 
65 FILLER PIC X(32) 

VALUE "Monetary Right Enclosure Symbol:". 
65 FILLER PIC X(@5) VALUE SPACE. 
@5 D8-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. . 
@5 FILLER PIC X(@3) VALUE SPACE. 
85 D8-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) VALUE SPACE. 
DF-9. 
@5 FILLER. PIC X(32) 

VALUE "Numeric Thousands Separator: ae 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D9-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) VALUE SPACE. 
@5 D9-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) VALUE SPACE. 
DF-19. 
@5 FILLER PIC X(32) 

VALUE "Numeric Decimal Symbol: ur 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D1O-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) VALUE SPACE. 
85 D19-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) VALUE SPACE. 
DF-11. 
@5 FILLER PIC X(32) 
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VALUE "Numeric Positive Symbol: a 


@5 FILLER PIC X(@5) VALUE SPACE. 
®5 0O11-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) VALUE SPACE. 
@5 D11-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) VALUE SPACE. 
G1 DF-12. 
@5 FILLER PIC X(32) 
VALUE "Numeric Negative Symbol: ae 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D12-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) VALUE SPACE. 
@5 D12-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) VALUE SPACE. 
91 DF-13. 
@5 FILLER PIC X(32) 
VALUE "Numeric Left Enclosure Symbol: ". 
@5 FILLER PIC X(@5) VALUE SPACE. 
85 D13-SYMLEN-ELEM PIC ZZZZZ2ZZZZZZ9. 
@5 FILLER PIC X(@3) | VALUE SPACE. 
85 D13-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) VALUE SPACE. 
@1 DF-14. 
@5 FILLER PIC X(32) 
. VALUE "Numeric Right Enclosure Symbol: ". 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D14-SYMLEN-ELEM PIC 2Z2ZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) VALUE SPACE. 
@5 D14-SYM-ELEM PIC X(12). 
@5 FILLER PIC X(16) | VALUE SPACE. 
@1 DF-15. 
@5 FILLER PIC X(32) 
VALUE "Monetary Grouping Specification:". 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D15-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) | VALUE SPACE. 


@5 015-SYM-ELEM. 
18 D15-SYM-1 PIC X(12). 
19 D15-SYM-2 PIC X(12). 


@5 FILLER PIC X(16) VALUE SPACE. 
G1 DF-16. 
@5 FILLER PIC X(32) 
VALUE "Numeric Grouping Specification: ". 
@5 FILLER PIC X(@5) VALUE SPACE. 
@5 D16-SYMLEN-ELEM PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(@3) VALUE SPACE. 


@5 D16-SYM-ELEM. 
19 D16-SYM-1 PIC X(12). 
- 18 D16-SYM-2 PIC X(12). 
@5 FILLER PIC X(16) | VALUE SPACE. 
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*** The following global declarations are used as parameters *** 
*** to the CENTRALSUPPORT procedures. eee 


KEEKKEKKREKEREREREREEREEEKRERKEEREREREKRKEKRERRERRERRRERERERRRKEK KREIS 


@1 CNV-NAME PIC X(17). 
G1 SYM-ARY. 

@5 SYM-ELEM PIC X(12) OCCURS 18 TIMES. 
@1 SYMLEN-ARY USAGE BINARY. 

@5 SYMLEN-ELEM PIC $9(11) OCCURS 17 TIMES. 
77 -CS-DATAOKV PIC $9(11) USAGE BINARY — VALUE 1. 
77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 
77 MAX PIC $9(11) USAGE BINARY VALUE 18. 
77 RESULT PIC $9(11) USAGE BINARY. 
77 SUB PIC $9(11) USAGE BINARY. 
77. TOTAL PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
DISPLAY "*** INTL_COBOL74: CNV_SYMBOLS". 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-SYMBOLS. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


KEKE CNV-SYMBOLS KEKKKKEKEKKKEKEKEKEREEKRKEEEREERKEREEKEREREERERERERREE 


CNV-SYMBOLS. 
CHANGE ATTRIBUTE LIBACCESS OF “CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "Norway" TO CNV-NAME. 
CALL "CNV_SYMBOLS OF CENTRALSUPPORT" 
USING CNV-NAME, 
TOTAL, 
SYMLEN-ARY, 
SYM-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE SPACE TO OUTPUT-RECORD 
WRITE OUTPUT-RECORD 
WRITE OUTPUT-RECORD FROM OF-2 
WRITE OUTPUT-RECORD FROM OF-3 
MOVE 1 TO SUB 
PERFORM DISPLAYARY UNTIL SUB IS GREATER THAN MAX. 


k*KKKK DISPLAYARY KKKEKKEREKKERERKKERKEKEEREEREEREEREEREERERRRRERKREKER 


DISPLAYARY. 
IF SUB IS EQUAL TO 1 
THEN MOVE SYMLEN-ELEM(SUB) TO D1-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D1-SYM-ELEM 
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8600 0296-000 


16-71 


Internationalization 


16-72 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
_ THEN 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
THEN 


IF SUB 
THEN 


WRITE OUTPUT-RECORD FROM DF-1. 
IS EQUAL TO 2 
MOVE SYMLEN-ELEM(SUB) TO D2-SYMLEN-ELEM 


MOVE SYM-ELEM(SUB) TO D2-SYM-ELEM 


WRITE OUTPUT-RECORD FROM DF-2. 

IS EQUAL TO 3 

MOVE SYMLEN-ELEM(SUB) TO D3-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D3-SYM-ELEM 

WRITE OUTPUT~RECORD FROM DF-3. 

IS EQUAL TO 4 

MOVE SYMLEN-ELEM(SUB) TO D4-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D4-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-4. 

IS EQUAL TO 5 

MOVE SYMLEN-ELEM(SUB) TO D5-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D5-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-5. 

IS EQUAL TO 6 

MOVE SYMLEN-ELEM(SUB) TO D6-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D6-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-6. 

IS EQUAL TO 7 

MOVE SYMLEN-ELEM(SUB) TO D7-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D7-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-7. 

IS EQUAL TO 8 . 

MOVE SYMLEN-ELEM(SUB) TO D8-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D8-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-8. 

IS EQUAL TO 9 . 

MOVE SYMLEN-ELEM(SUB) TO D9-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D9-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-9. 

IS EQUAL TO 18 

MOVE SYMLEN-ELEM(SUB) TO D1@-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D19-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-19. 

IS EQUAL TO 11 

MOVE SYMLEN-ELEM(SUB) TO D11-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D11-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-11. 

IS EQUAL TO 12 

MOVE SYMLEN-ELEM(SUB) TO D12-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D12-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF- Aes 

IS EQUAL TO 13 

MOVE SYMLEN-ELEM(SUB) TO D13-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D13-SYM-ELEM 

WRITE OUTPUT-RECORD FROM DF-13. 

IS EQUAL TO 14 

MOVE SYMLEN-ELEM(SUB) TO Di4-SYMLEN-ELEM 
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MOVE SYM-ELEM(SUB) TO D14-SYM-ELEM 
WRITE OUTPUT-RECORD FROM DF-14. 
IF SUB IS EQUAL TO 15 . 
THEN MOVE SYMLEN-ELEM(SUB) TO D15-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D15-SYM-1. 
IF SUB IS EQUAL TO 16 
THEN MOVE SYMLEN-ELEM(SUB) TO D16-SYMLEN-ELEM 
MOVE SYM-ELEM(SUB) TO D15-SYM-2 
WRITE OUTPUT-RECORD FROM DF-15. 
IF SUB IS EQUAL TO 17 
THEN MOVE SYM-ELEM(SUB) TO D16-SYM-1. 
IF SUB IS EQUAL TO 18 
THEN MOVE SYM-ELEM(SUB) TO D16-SYM-2 
WRITE OUTPUT-RECORD FROM DF-16. 
ADD 1 TO SUB. 


Example 16-16. Calling the CNV_SYMBOLS Procedure (cont.) 


Explanation 


CNV-NAME is passed to the procedure. It contains the name of the convention to be 
used to retrieve the monetary and numeric symbols. If this parameter contains all 
blanks or zeros, the procedure will use the hierarchy to determine the convention to be 
used. Refer to the MLS Guide for the list of convention names and the explanation of 
the hierarchy. 


TOTAL is returned by the procedure. It contains the total number of symbols returned. 


SYMLEN-ARY is returned by the procedure. It contains the lengths of all symbols being 
returned in SYM-ARY. The recommended length of SYM-ARY is 16 words. 


SYM-ARY is returned by the procedure. Each element of the record contains a 
symbol defined in the monetary and numeric template for the specified convention. 
The corresponding entry in SYMLEN-ARY contains the length of each symbol. The 
maximum length of SYM-ARY is 216 bytes. _ . 


SYMLEN-ARY and SYM-ARY are parallel records. Each entry in SYMLEN-ARY 
specifies the number of characters the corresponding entry in SYM-ARY has. If an 
entry in SYMLEN-ARY is 0 (zero), it indicates that the symbol is not defined and the 
corresponding entry in SYM-ARY is filled with blanks. If an entry in SYMLEN-ARY is 
not 0 (zero), but the corresponding entry in SYM-ARY is all blanks, then the number of 
blanks specified by the SYMLEN-ARY entry forms the symbol. 


The procedure returns the monetary and numeric templates defined by the convention 
in fixed-length fields. Each field is 12 bytes long except where noted. 
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The following table shows the monetary and numeric symbols that are returned in the 
record SYM-ARY and the offset in bytes of the field in which the symbol is returned: 


Monetary Symbol Offset Numeric Symbol = Offset 
International currency 0 Thousands separator 96 
notation 

National currency symbol 12 ‘Decimal symbol 108 
Thousands separator 24 Positive sign 120 
Decimal symbol 36 Negative sign - 132 
Positive sign - 48 Left enclosure 144 
Negative sign 60 Right enclosure 156 
Left enclosure 72 Monetary grouping ‘168 
Right enclosure 84 . Numeric grouping | 192 


The monetary and numeric grouping each occupy two adjacent fields (24 bytes) in 
SYM_ARY. The monetary and numeric groupings, when present, are character strings 
consisting of unsigned integers separated by commas. The integers specify the number 
of digits in each group and appear exactly as declared in the monetary and numeric 
templates including embedded commas. 


The following table shows the offset in bytes of the fields in the record SYMLEN-ARY, 
which contain the symbol lengths for the monetary and numeric symbols: 


Offset Contains Length of Offset Contains Length of 
0 International currency 8 Numeric thousands 
notation separator symbol 
] National currency symbol 9 Numeric decimal symbol 
2 Monetary thousands 10 — Numeric positive symbol 
separator 
3 Monetary decimal symbol 11 Numeric negative symbol 
4 Monetary positive symbol 12 Numeric left enclosure 
. symbol 
5 Monetary negative symbol 13 Numeric right enclosure 
symbol 
6 Monetary left enclosure 14 Monetary grouping 
symbol 
rf Monetary right enclosure 15 Numeric grouping 
symbol 


MAX is not a parameter but a constant with the value of 18. This constant ensures that 
SUB, a subscript of the SYM-ELEM and SYMLEN-ELEM arrays, does not exceed 18. 
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RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV-SYMBOLS are as follows: 


1 2002 3002 
2 2004 . 3011 
1001 3000 
1002 ~ 3001 


Sample output from Example 16-16 follows: 
RESULT = 1 


Field Meaning — Symbols Length Convention Symbols 
International Currency Notation: 
National Currency Notation: 
Monetary Thousands Separator: 
Monetary Decimal Symbol: 
Monetary Positive Symbol: 
Monetary Negative Symbol: 
Monetary Left Enclosure Symbol: 
Monetary Right Enclosure Symbol: 
Numeric Thousands Separator: 
Numeric Decimal Symbol: 

Numeric Positive Symbol: 

Numeric Negative Symbol: 

Numeric Left Enclosure Symbol: 
Numeric Right Enclosure Symbol: 
Monetary Grouping Specification: 
Numeric Grouping Specification: 


PRP QQH QHYE KH QQHeK QR K WW 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CNV_SYSTEMDATETIMETMP_COB 


This procedure formats the system date, the system time, or both according to 

a template and language that you supply. The system obtains the date and time 
from a single function call to avoid the possibility of splitting the date and time 
across a day boundary. The template may be retrieved for any convention from the 
CNV_TEMPLATE COB procedure or may be created by the user. 


Example 


Example 16-17 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_SYSTEMDATETIMETMP_COB library procedure. 
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The declarations identify the category of data-item required for parameter matching. 
For example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose paar names that are 


appropriate = your use. 


This example formats system date and time according to a template provided by the 
calling program in TMP-ARY. The formatted date and time are translated to English 
and returned in SDT-ARY. DTEMP-LEN is set to the length of the date template in 


TMP-ARY. 


IDENTIFICATION DIVISION. 


ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 


SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 


LABEL RECORD IS STANDARD 

VALUE OF TITLE IS "OUT/COBOL74/CNVSYSDATETIMETMP. " 
PROTECTION SAVE 

RECORD CONTAINS 8@ CHARACTERS 

DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8@). 

WORKING-STORAGE SECTION. 

81 OF-1. . 
@5 FILLER PIC X(@9) VALUE "RESULT = 
@5 OF-RESULT PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(59) VALUE SPACE. 

81 OF-2. . 
@5 FILLER PIC X(1@) VALUE "SDT-ARY = 
@5 OF-SDT-ARY PIC X(4@). 
®5 FILLER PIC X(3@) VALUE SPACE. 


KEKKKKKKEKEKKEEERKKREKEKEREEREREREREREREEREREKEREERERERERREERRERRRREER 


kkk 
kkk 


‘The following global declarations are used as parameters 
to the CENTRALSUPPORT procedures. 


kkk 


kkk 


KKEKKKEKKKERKKEEREKEKKERERERKEERRKRERKRERERKERERKERREREEREERRERRERKRRERREERE 


@1 LANG-NAME PIC X(17). 
@1 SDT-ARY PIC X(49). 
@1 TMP-ARY PIC X(48). 
77 CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE 9. 
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77 DTEMP~LEN PIC $9(11) USAGE BINARY. 
77 RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
-INTLCOBOL74. 
DISPLAY "*** INTL_COBOL74: CNV_SYSTEMDATETIMETMP_ COB". 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-SYSTEMDATETIMETMP-COB. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


kkkeKK CNV-SYSTEMDATET I METMP-COB KEREKEKKKEKKERERKREEKRKKRKRKKKRKKRKRKKKEE 
CNV-SYSTEMDATETIMETMP-COB. 
CHANGE ATTRIBUTE LIBACCESS OF “CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "IW!, INE IDI, !YYYY! !6T!:!QM!:1@S!" TO TMP-ARY. 
MOVE 21 TO DTEMP-LEN. 
MOVE "ENGLISH" TO LANG-NAME. 
CALL "CNV_SYSTEMDATETIMETMP_COB OF CENTRALSUPPORT" 
USING TMP-ARY, 
LANG-NAME , 
DTEMP-LEN, 
SDT-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE SDT-ARY TO OF-SDT-ARY 
WRITE, OUTPUT-RECORD FROM OF-2. 
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TMP-ARY is passed to the procedure. It contains the template you specify, left-justified 
in the field. The recommended length of a template is 48 characters. If both date and 
time templates are present, the date template must appear first. Refer to the MLS 
Guide for information about creating a template. 


LANG-NAME is passed to the procedure. It contains the name of the language to be 
used in formatting the date, the time value or both. If this parameter contains all blanks 
or zeros, the procedure uses the hierarchy to determine the language to be used. Refer 
to the MLS Guide for information about determining the valid ee names on your 
system and the explanation of the hierarchy. 


DTEMP-LEN is an integer passed by reference to the procedure. It specifies the length 
of the date template in TMP-ARY. If DTEMP-LEN is 0 (zero), it indicates there is no 
date template in TMP-ARY. If you specify both a date and time template, then the date 
template must appear first in TMP-ARY. The date and time are formatted if both date 
and time templates are present, the date is formatted if only date template is present, 
and the time is formatted if only time template is present. 
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SDT-ARY is returned by the procedure. It contains the formatted date, formatted time, 
or both. The recommended length of the formatted value is 45 characters. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_SYSTEMDATETIMETMP COB are as follows: 


1 : 2001 3002 
2 2003 | 3011 
1001 3000 
1002 3001 


Sample output from Example 16-17 follows: 


RESULT = 1 
SDT-ARY = Thursday, March 7, 1991 18:31:23 


See Also 


For more information on the error result values, see Table 16—2 later in this section. 


CNV_SYSTEMDATETIME_COB- 


16-78 


_. This procedure formats the system date, the system time, or both according to the 


specified convention. It translates the date and time components to the natural language 
you specify. The system computes both the date and time from the result of a single 
function call. Thus, the possibility that the date and time are split across midnight does 
not exist. 


You might use this procedure to output the system date and time in the Spain 
convention and the Spanish language, for example. 


Example 


Example 16-18 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CVNV_SYSTEMDATETIME COB library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose peremere) names that are 
appropriate for your use. 


This example formats the system date and time according to formatting definitions 

in the ASeriesNative convention. The form of date and time is specified by _ 

CS-LDATENTIMEV (long date and numeric time). Formatted date and time are 
translated to English and returned in SDT-ARY. 
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IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS “OUT/COBOL74/CNVSYSDATETIME." 
PROTECTION SAVE 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


G1 OF-1. | 
@5 FILLER PIC X(69) VALUE “RESULT = ". 
@5 OF-RESULT PIC ZZZZZZZ22229. © 
@5 FILLER PIC X(59) VALUE SPACE. 

G1 OF-2. 
@5 FILLER | PIC X(18) VALUE "SDT-ARY = ". 
@5 OF-SDT-ARY PIC X(4@). 
@5 FILLER PIC X(3@) | VALUE SPACE. 


KEKKEKKEKKEKEERKEREKRKKERKEKEREERKEKRKEREREKEREKREEREEREREKRKREREKREKEKREKEK 


*** The following global declarations are used as parameters *** 


*** to the CENTRALSUPPORT procedures. RES 
KEEKEKRERKEREKEKKEREEEKERRERRERERKEREREREKREKRREREERREERERKEEKEERKREEEREREREE 
1 CNV-NAME PIC X(17). 

01 LANG-NAME PIC X(17). 

81 SDT-ARY “PIC X(49). 

77 CS-DATAOKV “PIC $9(11) USAGE BINARY VALUE 1. 

77 +CS-FALSEV PIC $9(11) USAGE BINARY VALUE 9. 

77 ~CS-LDATENTIMEV PIC $9(11) USAGE BINARY VALUE 6. 

77 RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 

INTLCOBOL74. , 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-SYSTEMDATETIME-COB. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


KEKKK CNV-SYSTEMDATETIME-COB KRKEKEEKEKERKEREEERKERKEKERREKKKEEREREEKEE 


CNV-SYSTEMDATETIME-COB. 


Example 16-18. Calling the CNV_SYSTEMDATETIME_COB Procedure 
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CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "ASERIESNATIVE" TO CNV-NAME. | 
MOVE "ENGLISH" TO LANG-NAME. 
CALL "CNV_SYSTEMDATETIME_COB OF CENTRALSUPPORT" 
USING CS-LDATENTIMEV, 
CNV-NAME, 
LANG-NAME, 
SDT-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE SDT-ARY TO OF-SDT-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-18. Calling the CNV_SYSTEMDATETIME_COB Procedure (cont.) 


Explanation 


CS-LDATENTIMEV is passed to the procedure. It indicates one of the following formats 
is used when the date and time are returned: 


Value Sample Data Item Meaning 
0 — CS-LDATEV | Long date format 
1 CS-SDATEV Short date format 
2 CS-NDATEV Numeric date format 
3 CS-LTIMEV Long time format 
4 CS-NTIMEV Numeric time format 
5 CS-LDATELTIMEV Long date and long time 
6 CS-LDATENTIMEV Long date and numeric time 
7 CS-SDATELTIMEV Short date and long time 
8 CS-SDATENTIMEV Short date and numeric time 
9 CS-NDATELTIMEV Numeric date and long time 
10 CS-NDATENTIMEV - Numeric date and numeric time 


CNV-NAME is passed to the procedure. It contains the name of the convention to be 
used to edit the date and time value. If this parameter contains all blanks or zeros, the 
procedure will use the hierarchy to determine the convention to be used. Refer to the 
MLS Guide for the list of convention names and the explanation of the hierarchy. 


LANG-NAME is passed to the procedure. It contains the language to be used in 
formatting the date and time value. If this parameter contains all blanks or zeros, the 
procedure will use the hierarchy to determine the language to be used. Refer to the 
MLS Guide for information about determining the valid language names on your system 
and the explanation of the hierarchy. , 
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SDT-ARY is returned by the procedure. It contains the formatted date, formatted time, 
or both. The recommended length of the formatted value is 40 characters. — 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_SYSTEMDATETIME COB are as follows: 


1 2001 3000 
Z 2002 3001 
1001 | 2003 3006 
1002 2004 3011 


Sample output from Example 16-18 follows: 
RESULT = 1 
SDT-ARY = Wednesday, November 7, 1998 17:14:58 


See Also 


For more information on the error result values, see Table 16—2 later in this section. 


CNV_TEMPLATE_COB 
This procedure returns the requested format template for a designated convention. 


You might want to use this procedure to improve the performance of your program. By 
retrieving and storing a template that you want to use in many places, you can improve 
the performance of your program by eliminating the calls to the CENTRALSUPPORT 
library. 


Example 


Example 16-19 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the CNV_TEMPLATE COB library procedure. The declarations 
identify the category of data-item required for parameter matching. For example, 
numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example retrieves a monetary editing template from the Turkey convention. The 
template is returned in TMP-ARY. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 


Example 16-19. Calling the CNV_TEMPLATE_COB Procedure 
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FI 


DA 
FI 
FD 


G1 


WO 


G1 


G1 


LE-CONTROL. 


SELECT OUTPUT-FILE ASSIGN TO DISK. 


TA DIVISION. . 
LE SECTION. 
OUTPUT-FILE 
LABEL RECORD IS STANDARD 


VALUE OF TITLE IS "OUT/COBOL74/CNVTEMPLATECOB." 


PROTECTION SAVE 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


OUTPUT-RECORD PIC X(8@). 
RKING-STORAGE SECTION. 
OF-1. 
@5 FILLER PIC X(@9) VALUE "RESULT = ". 
@5 OF-RESULT PIC ZZZZZZZZ2229. 
@5 FILLER PIC X(59) | VALUE SPACE. 
OF-2. | 
@5 FILLER PIC X(18) | VALUE "TMP-ARY = “. 
@5 OF-TMP-ARY PIC X(48). 
05 FILLER PIC X(22) VALUE SPACE. 


KREKKKKEKREERKKEEREKKEKEKEEKKKKEKRREKKREKKKREKRERREKERREEEKRRKREKREEKKKEEKKKKRKE 


xkk 


kkk 


The following global declarations are used as parameters *** 


to the CENTRALSUPPORT procedures. 


kkk 


KKEKREKKEKKKEREEKRERRERERRREREREKRREREERERRKEEKERERERRKEREKERREERRKEREEEE 


G1 
G1 


77 
77 
77 
77 


PR 
IN 


CNV-NAME PIC X(17). 

TMP-ARY PIC X(48). 

CS-DATAOKV PIC $9(11) 

CS-FALSEV PIC $9(11) 

CS-MONETARY-TEMPV PIC. $9(11) 

RESULT PIC $9(11) 
OCEDURE DIVISION. 


TLCOBOL74. 

OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-TEMPLATE-COB. 
CLOSE OUTPUT-FILE. 

STOP RUN. 


USAGE BINARY 
USAGE BINARY 
USAGE BINARY 


USAGE BINARY. 


VALUE 1. 
VALUE @. 
VALUE 5. 


KEKE CNV-TEMPLATE-COB RAE ne Ot RN eee Re Re Ne Renae 


CN 
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V-TEMPLATE-COB. 


CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 


MOVE "Turkey" TO CNV-NAME. 


CALL "CNV_TEMPLATE_COB OF CENTRALSUPPORT" 


USING CS-MONETARY-TEMPV, 


Example 16-19. Calling the CNV_TEMPLATE_COB Procedure (cont.) 
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CNV-NAME , 
TMP~ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN STRING TMP-ARY DELIMITED BY @28@, 
-@2G@ DELIMITED BY SIZE 
INTO OF-TMP-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-19. Calling the CNV_TEMPLATE_COB Procedure (cont.) 


Explanation 


CS-MONETARY-TEMPYV is passed to the procedure. It specifies the type of template to 
be returned. This parameter can have the following values: 


Value Sample Data Item > Template to be Retrieved 
0) CS-LONGDATE-TEMPV | Long date 
1 CS-SHORTDATE-TEMPV Short date 
2 CS-NUMDATE-TEMPV Numeric date 
3 CS-LONGTIME-TEMPV Long time 
4 CS-NUMTIME-TEMPV Numeric time 
5 CS-MONETARY-TEMPV Monetary template 
6 


CS-NUMERIC-TEMPV Numeric template 


CNV-NAME is passed to the procedure. It contains the name of the convention that 

you specify. If this parameter contains all blanks or zeros, the procedure will use the 
hierarchy to determine the convention to be used. Refer to the MLS Guide for the list of 
convention names and the explanation of the hierarchy. 


TMP-ARY is returned by the procedure. It contains the requested template. The 
recommended length of a template is 48 characters. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by CNV_TEMPLATE COB are as follows: 


: 2002 3002 
1001 3000 3006 
1002 3001 
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2 


Sample output from Example 16-19 follows: 


RESULT = 1 | 
TMP-ARY = !T[.:8,3]D[,]#N[-]C[T]! 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 


CNV_VALIDATENAME 


This procedure returns a value in the procedure result that indicates whether the 
convention name you specified is currently defined on the host system. 


You might use this procedure to ensure that a convention used as an input parameter 
exists on the system on which your program is running. 


Example 


Example 16—20 shows the parameter declarations and the PROCEDURE DIVISION | 
syntax required to call the CVV_VALIDATENAME library procedure. The declarations 

_ identify the category of data-item required for parameter matching. For example, 
numeric items must be declared PIC 89(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example determines whether or not a convention named Sweden is currently 
available on the system. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OQUTPUT-FILE 
LABEL RECORD IS STANDARD . 
VALUE OF TITLE IS “OUT/COBOL74/VALIDATENAME. " 
PROTECTION SAVE 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


Example 16-20. Calling the CNV_VALIDATENAME Procedure 
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61 OF-1. 
@5 FILLER . PIC X(@9) VALUE "RESULT = 
65 OF-RESULT PIC 222222222229. 
@5 FILLER PIC X(59) VALUE SPACE. 


KKEKEKEKKEKEKRRKREREREREREKEEEREKREREEKRERKEKERKEEREERERERREREKRERKKKKRKKKKKE 


*** The following global declarations are used as ca eka 
**x* to the CENTRALSUPPORT procedures. weK 


KKEKKKEEKKEEKERKKEEREERKREKREREREERREEEEREREREEKRERKRKRERERERKEEKKEKRRRREREEE 


G1 CNV-NAME PIC X(17). 

77 CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 
77. RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM CNV-VALIDATENAME. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


kkEKK CNV-VALIDATENAME KKKEKKEKEKEEKKEKEEEREEERRKEREEKREREEKEKRERERERE 


CNV-VALIDATENAME. 
CHANGE ATTRIBUTE LIBACCESS OF "“CENTRALSUPPORT" TO BYFUNCTION.: 
MOVE "Sweden" TO CNV-NAME. | 
CALL "CNV_VALIDATENAME OF CENTRALSUPPORT" 
USING CNV-NAME 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 


Example 16-20. Calling the CNV_VALIDATENAME Procedure (cont.) 


Explanation | 


CNV-NAMB, is passed to the procedure. It contains the name of the convention that is 
to be checked. If this parameter contains all blanks or nulls, the RESULT parameter 
returns a value of 0 (zero) or FALSE. Refer to the MLS Guide for the list of convention _ 
names and the explanation of the hierarchy. 


RESULT is an integer that is returned by the procedure. It contains the procedure 
result. The possible values for RESULT and their meanings are as follows: 


Value Condition-Name Meaning 
0 CS-FALSEV The convention name is not valid. 
1 CS-DATAOKV - The convention name is valid. 
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Sample output from Example 16-20 follows: 


RESULT = g 


GET CS _ MSG 


This procedure returns message text associated with the designated message number. 
The message number is obtained as the result value returned from a call to any of the 
~ CENTRALSUPPORT procedures. 


When calling the GET_CS_ MSG procedure, you can designate the language to which 
the message is to be translated and the desired length of the returned message. If the 
returned text is shorter than the length specified, the procedure pads the remaining 
portion of the record with blanks. 


An entire message consists of the following three parts: 


e The header, which comprises the first 80 characters of the message text returned 
by the MSG parameter. The text in the header provides the message number and a 
concise text description. 


e The short description, which comprises the second 80 character of the message text 
returned by the MSG parameter. If space is a consideration, you might want to limit 
the description of the message to the header and short description. 


e The long description, which comprises the remaining characters of the message 
text returned by the MSG parameter. The long description provides a complete 
_ explanation of the message that was returned. 


Part or all of the message text can be returned. Note that the header part starts at 
offset 0 (zero), the short description at offset 80, and the long description at offset 160. 
For example, if you specify the MSG-LEN parameter to be equal to 200 characters, then 
the MSG parameter would contain the header message padded with blanks to offset 

80, if necessary, followed by the short description padded with blanks to offset 160, if 
necessary, followed by the first 40 characters of the long descripHon. 


The message length should be at least 80 characters, equal to one line of text. Anything 
less results in an incomplete message. Unisys recommends using a value of either 80, 
160, or 999. The value of 999 causes the entire message to be returned. 


You might want to use this procedure to retrieve the text of an error message so that it 
can be displayed by your program. 


Example 


Example 16-21 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the GET_CS_MSG library procedure. The declarations identify 
the category of data-item required for parameter matching. For example, numeric items 
must be declared PIC S9(11) USAGE BINARY. 
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In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example illustrates how to get the message text associated with a 
CENTRALSUPPORT error message. Assume that the sample call to 
VALIDATE NAME RETURN. NUM returns the error 3004 (The requested name was 
not found.). When the error is returned, this example gets the first 160 characters (2 
lines) of the message text for the error. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS “OUT/COBOL74/GETCSMSG." 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD . PIC X(8@). 


WORKING-STORAGE SECTION. 


01 OF-1. 
@5 FILLER PIC X(39) 
VALUE "RESULT FROM VALIDATE_NAME_RETURN_NUM = ". 
85 OF-RESULT1 PIC ZZZZZ2ZZZZZZ9. 
@5 FILLER PIC X(23) VALUE SPACE. 
G1 OF-2. 
85 FILLER PIC X(39) 
VALUE "RESULT FROM GET_CS_MSG mee 
65 OF-RESULT2 PIC 2ZZZ2ZZZZ2Z2Z9. 
@5 FILLER PIC X(23) VALUE SPACE. 
91 OF-3. 
65 FILLER . PIC X(66) VALUE "MSG = ". 
65 FILLER PIC X(74) VALUE SPACE. 
01 OF-4. 
85 OF-MSG PIC X(8@). 


HICK HIKARI AREA IKARIA IAIN IAIN IEA AIA I AMIEA IAA AAAI AIAIIANAIAAIA 


*** The following global declarations are used as parameters *** 
*** to the CENTRALSUPPORT procedures. cad 


KKKKREKEREKEKRKREKREREKEREEEKKEKREKEEKEKKREKREKRKEKEREEEREEEREREEREEREE 


81 LANG-NAME PIC X(17). 
Example 16-21. Calling the GET_CS MSG Procedure 
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16-88 


91 MSG. 


@5 MSG-ELEM 
91 NAME-ARY 


77 CS-CHARACTER-SETV 
77 ~CS-DATAOKV 

77 ~=CS-FALSEV 

77 MSG-LEN 

77 NUM 

77 RESULT1 

77 ~=RESULT2 


PROCEDURE DIVISION. 
INTLCOBOL74. 


PIC 
PIC 


PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 


X (88) 
X(17). 


$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 


OCCURS 2 TIMES. 


USAGE BINARY VALUE 9. 
USAGE BINARY VALUE 1. 
USAGE BINARY VALUE @. 
USAGE BINARY.. 
USAGE BINARY. 
USAGE BINARY. 
USAGE BINARY. 


DISPLAY "*** INTL_COBOL74: GET_CS MSG". 
OPEN OUTPUT OUTPUT-FILE. 


PERFORM GET-CS-MSG. 
CLOSE OUTPUT-FILE. 
STOP RUN. | 


KekKK GET-CS -MSG KKKKKKKKEKKKEEKEEKEEKKEKKKKEKKREKEREKREERERKKREKAEKK 


GET-CS-MSG. 


CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 


MOVE "BADNAME" TO NAME-ARY. 


CALL "VALIDATE_NAME_RETURN_NUM OF CENTRALSUPPORT" 
USING CS-CHARACTER-SETV, : 


NAME-ARY, 
NUM 
GIVING RESULT1. 


MOVE RESULT1 TO OF-RESULT1. 


_ WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT1 IS NOT EQUAL TO CS-DATAOKV 
THEN MOVE 168 TO MSG-LEN 
CALL "GET_CS_ MSG OF CENTRALSUPPORT" 


USING RESULT], 


LANG-NAME, 


MSG, 


MSG-LEN 
GIVING RESULT2 
MOVE RESULT2 TO OF-RESULT2 


WRITE OUTPUT-RECORD FROM OF-2 
WRITE OUTPUT-RECORD FROM OF-3 


MOVE MSG-ELEM(1) TO OF-MSG 


WRITE OUTPUT-RECORD FROM OF-4 


MOVE MSG-ELEM(2) TO OF-MSG 


WRITE OUTPUT-RECORD FROM OF-4. 
Example 16-21. Calling the GET_CS MSG Procedure (cont.) 
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Explanation 


NUM is passed to the procedure. It contains the number of the message for which 
you want the text. These values are returned by calls on other CENTRALSUPPORT 
procedures. The message numbers and their meanings are listed at the end of this 
section. 


LANG-NAME is passed to the procedure. It specifies the language in which the 

message is to be displayed. The maximum length of a language name is 17 characters. 

If this parameter contains all blanks or zeros, the procedure uses the default language 
hierarchy to determine the language to be used. Refer to the MLS Guide for details 
about determining the valid language names on the system and for the explanation of the 
default language hierarchy. 


MSG is returned by the procedure. It contains the message text associated with the 
specified message number. Unisys recommends the size of this record be at least 80 
characters. 


MSG-LEN in passed to the procedure. For an output parameter, MSG_LEN contains 
an update value. For input, it specifies the maximum length of the message to be 
returned. If MSG-LEN is equal to 0 (zero), one line of text (80 characters) is returned. 
If MSG-LEN is between 1 and 79, then only a partial message is returned. MSG-LEN 
should not be greater than the size of the MSG record. Recommended values for 
MSG-LEN are 80, 160, or a large number that returns all of the message. For output, 

- MSG _LEN specifies the actual length of the message returned by the procedure. 


NAME-ARY is passed to the procedure. It contains the coded character set or ccsversion 
name for which a message number is being requested. The name can be up to 17 
characters long. If this parameter contains zeros or blanks, the procedure uses the 
hierarchy to determine the ccsversion or character set to be used. If there is no system 
default, the procedure returns an error in RESULT. 


CS-CHARACTER-SETV is passed to the procedure. If this flag represents 0 (zero), the . 
coded character set is being checked. If it represents 1 (one), the ccsversion is being 
checked. © 


RESULT1 is passed to the procedure. It contains the number of the message for which 
you want the text. These values are returned by calls on other CENTRALSUPPORT 
procedures. The message numbers and their meanings are listed at the end 

of this section. In Example 16-21, the RESULT1 field is from an executed 
VALIDATE NAME RETURN_NUM procedure that requested a ccsversion number for 
the name BADNAME. 


RESULT2 is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by GET_CS_MSG are as follows: 


1 2004 3002 


1001 3000 3003 
1002 3001 
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Sample output from Example 16-21 follows: 


RESULT FROM VALIDATE_NAME_RETURN_NUM 
RESULT FROM GET_CS_ MSG 

MSG = 

>>> CENTRALSUPPORT INTERFACE ERROR (#3804) <<< 
INVALID CHARACTER SET OR CCSVERSION NAME 


3084 


ie 
iy 


See Also 


For more information on the error result values, see Table 16~2 later in this section. 


MCP_BOUND_LANGUAGES 


16-90 


This procedure returns the names of languages that are currently bound to the 
operating system. For information about binding a language to the operating system, 


_ refer to the MLS Guide. 


You might use this procedure to determine which languages are available on the system. 


Example 


Example 16-22 shows the parameter declarations and the PROCEDURE DIVISION © 
syntax required to call the MCP_BOUND_LANGUAGES library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC §9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example returns the languages bound by the operating system. Assume for this 
example that the bound language is English. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OQUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "OUT/COBOL74/MCPBOUNDLANGUAGES. " 
PROTECTION SAVE SS 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


81 OQUTPUT-RECORD PIC X(8@). 


Example 16-22. Calling the MCP_BOUND_LANGUAGES Procedure 
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WORKING-STORAGE SECTION. 


G1 OF-1. 
@5 FILLER PIC X(@9) VALUE "RESULT = ". 
@5 OF-RESULT PIC ZZZZZZZZZZZ9. 
@5 FILLER - PIC X(59) VALUE SPACE. 
G1 OF-2. | 
@5 FILLER PIC X(@9) VALUE "Languages". 
@5 FILLER PIC X(71) VALUE SPACE. 
81 OF-3. 
@5 FILLER PIC X(@9) VALUE ALL "-". 
@5 FILLER PIC X(71) | VALUE SPACE. 
@1 OF-4. 
@5 OF-LANG-ELEM PIC X(17). 
5 FILLER PIC X(63) VALUE SPACE. 


KEKKKKKKKKKKEEEKEERKEREEKERREKREREREKRKEEREEEREEKKREKRRREKRERREEKKRRREKK 


*x* The following global declarations are used as parameters *** 
*** to the CENTRALSUPPORT procedures. al 


TT TTTCTCCLLCCCLerrCCrrrreLe TT Le ELL eee. Le ee ee eee errs tree oa 


@1 LANGUAGES-ARY. . 
85 LANGUAGES-ELEM PIC X(17) OCCURS 2@ TIMES. 


G1 SUB PIC 9(@2). 

77 ~CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 ~CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 
77 ~=RESULT PIC S$9(11) USAGE BINARY. 

77 ~=TOTAL PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM MCP-BOUND-LANGUAGES. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


KkKEKK MCP-BOUND-LANGUAGES KKKKKEREEKEKERREKRKEKEKEKEKEREKEKREEEEEREEKRER 


MCP-BOUND-LANGUAGES. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
CALL "MCP_BOUND LANGUAGES OF CENTRALSUPPORT" 
-USING TOTAL, . 
LANGUAGES-ARY 
GIVING RESULT. | 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE SPACE TO OUTPUT-RECORD 
WRITE OUTPUT-RECORD 
WRITE OUTPUT-RECORD FROM OF-2 
WRITE OUTPUT-RECORD FROM OF-3 


Example 16-22. Calling the MCP_BOUND_LANGUAGES Procedure (cont.) 
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MOVE 1 TO SUB 
~ PERFORM DISPLAYLANGUAGESARY 
UNTIL SUB IS GREATER THAN TOTAL. 


keRKK DISPLAYLANGUAGESARY SNARES AITIA AR RE ER 


DISPLAYLANGUAGESARY . 
MOVE LANGUAGES-ELEM(SUB) TO OF-LANG-ELEM. 
WRITE OUTPUT-RECORD FROM OF-4. 
ADD 1 TO SUB. 


Example 16-22. Calling the MCP_BOUND_ LANGUAGES Procedure (cont.) 


Explanation 


TOTAL is an integer returned by the procedure. It contains the total number of 
languages that are bound to the operating system. 


LANGUAGES-ARY is returned by the procedure. It contains the names of the 
languages bound to the operating system. The maximum length of each name is 

17 characters, and the names are left justified. For any name that is less than 17 
characters, the field is filled on the right with blanks. In the example, the size of the 
record is 84 characters; a record of that size holds 5 names. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by this procedure are as follows: 


1 1002 3001 
1001 3000 


Sample output from Example 16-22 follows: 


RESULT = 1 


Languages 


ENGLISH 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 
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VALIDATE_NAME_RETURN_NUM 


This procedure examines a coded character set or ccsversion name to determine if it 
resides in the file SYSTEM/CCSFILE. The first parameter specifies whether you want to 
examine a coded character set or ccsversion. The next parameter specifies the name to 
be validated. The procedure returns the number of the coded character set or ccsversion 
in the last parameter. 


You might use this procedure to obtain the ccsversion number needed as a parameter to 
other CENTRALSUPPORT library procedures. 


Example 


Example 16-23 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the VALIDATE NAME _RETURN_NUM library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC $9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example checks to see if a ccsversion named CanadaGP is valid. Assume for this 
example that CanadaGP is valid and its associated number is 75. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE~CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD QUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "OUT/COBOL74/VALIDATENAMERTRN. " 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD - PIC X(8@). 


WORKING-STORAGE SECTION. 


@1 OF-1. a 
@5 FILLER PIC X(@9) VALUE "RESULT = " 
@5 OF-RESULT PIC ZZZZZZZ22229. 
@5 FILLER PIC X(59) | VALUE SPACE. 
G1 OF-2. 3 
@5 FILLER PIC X(@9) VALUE "NUM =" 


95 OF-NUM . PIC ZZZZZZ2ZZZZZ9. 
Example 16-23. Calling the VALIDATE_NAME_RETURN_NUM Procedure 


8600 0296-000 16-93 


Internationalization 


16-94 


65 FILLER PIC X(59) VALUE SPACE. 


KEEKRKKKKERREERKEEKEREEEEEKRKEEREREREREERRERERERKEERRERRKREKRERKEEERERKEEE 


*x** The following global declarations are used as parameters *** 


*** to the CENTRALSUPPORT procedures. “ae 
HKKKEKRKEKRKEEKERKERERRERRERERKRERERERERERREREREREKRREREREEREEKEEREREREREER 
91 NAME-ARY PIC X(17). 

77 ~=CS-CCSVERSIONV PIC $9(11) USAGE BINARY VALUE 1. 

77° ~CS=DATAOKV PIC S9(11) USAGE BINARY VALUE 1. 

77 CS-FALSEV PIC S9(11) USAGE BINARY VALUE @. 

77 NUM PIC S9(11) USAGE BINARY. 

77 RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM VALIDATE-NAME-RETURN-NUM. 
CLOSE OUTPUT-FILE. 
STOP RUN. . 


KkRKKK VALIDATE-NAME-RETURN-NUM KRKKEKKEKREREREREREEREREREREREREREREE 


VALIDATE-NAME-RETURN-NUM. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE "CanadaGP" TO NAME-ARY. 
CALL "VALIDATE_NAME_RETURN_NUM OF CENTRALSUPPORT" 
USING CS-CCSVERSIONV, 
NAME-ARY, 
_ NUM 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE NUM TO OF-NUM 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-23. Calling the VALIDATE_NAME_RETURN_NUM Procedure (cont.) 


Explanation 


CS-CCSVERSIONV is passed to the procedure. It indicates whether the entry specified 
in NAMB is a coded character set or cesversion name. The allowable values are as 
follows: 


Value Sample Data Item Meaning . 
) CS-CHARACTER-SET-V Coded character set name 
1 CS-CCSVERSION-V  Cesversion name 


NAME-ARY is passed to the procedure. It contains the coded character set or ccsversion 
name for which a number is being requested. The name can be up to 17 characters long. 
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If this parameter contains zeros or blanks and type is equal to 1, the procedure validates 
the system default ccsversion. 


NUM is returned by the procedure. It contains the coded character set or ccsversion 
number requested. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by VALIDATE NAME RETURN_NUM are as follows: 


1 3000 3006 
1001 3002 
1002 . 3004 


Sample output from Example 16-23 follows: 


RESULT = 1 
NUM = 75 
See Also 


For more information on the error result values, see Table 16-2 later in this section. 


VALIDATE_NUM_RETURN_NAME 


This procedure examines the number of a coded character set or ccsversion to determine 
if it resides in the SYSTEM/CCSFILE. The first parameter designates whether a coded 
character set or ccsversion is to be examined. The second parameter specifies the 
number to be validated. The procedure then returns the name of the given character 
set or ccsversion number. Refer to the MLS Guide for the list of numbers for coded 
character sets and ccsversions. 


You might use this procedure to display the name of the coded character set or the 
ccsversion being used. 


Example 


Example 16-24 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the VALIDATE NUM_RETURN_NAME library procedure. The 
declarations identify the category of data-item required for parameter matching. For 
example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 


appropriate for your use. 


This example checks to see if the ccsversion number 75 is valid. Assume for this example 
that 75 is valid and its associated name is CanadaGP. 
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IDENTIFICATION DIVISION. 


ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 


SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 


LABEL RECORD IS STANDARD 
VALUE OF TITLE IS “OUT/COBOL74/VALIDATENUMRTRN. " 


PROTECTION SAVE 


RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


61 OUTPUT~RECORD 


WORKING-STORAGE SECTION. 


PIC X(8@). 


81 OF-1. ; . 
65 FILLER PIC X(@9). VALUE "RESULT = ". 
85 OF-RESULT PIC 222222222229. 
@5 FILLER PIC X(59) VALUE SPACE. 
G1 OF-2. 
@5 FILLER PIC X(11) VALUE "NAME-ARY = ". 
@5 OF-NAME-ARY PIC X(17). 
@5 FILLER PIC X(52) VALUE SPACE. 
IESG GOO I I cick tekickicchthicktketek 
*** The following global declarations are used as parameters *** 
*** to the CENTRALSUPPORT procedures. eRe 
KEKRKEREEKREREEREKEEREKKRERERERKEERRERERKREEEEREKRREREREREEERERERERERREEER 
81 NAME-ARY PIC X(17). 
77 CS-CCSVERSIONV PIC $9(11) USAGE BINARY VALUE 1. 
77 ~CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE 9. 
77 NUM PIC $9(11) USAGE BINARY. 
77 RESULT PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 


OPEN OUTPUT OUTPUT-FILE. 
PERFORM VALIDATE-NUM-RETURN-NAME. 


CLOSE OUTPUT-FILE. 
STOP RUN. 


kkkRK VALIDATE-NUM-RETURN-NAME SRK ARIK IKARIA RAIA IIIA RA ARIA 


VALIDATE-~NUM-RETURN-NAME . 


CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. | 


Example 16-24. Calling the VALIDATE_NUM_RETURN_NAME Procedure 
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MOVE 75 TO NUM. 
CALL "VALIDATE_NUM RETURN NAME OF CENTRALSUPPORT" 
USING CS-CCSVERSIONV, 
NUM, 
NAME-ARY 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE NAME-ARY TO OF-NAME-ARY 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-24. Calling the VALIDATE_NUM_RETURN_ NAME Procedure (cont.) 


Explanation 


CS-CCSVERSIONV is passed to the procedure. It indicates whether the value specified 
in NUM is a coded character set number or a cesversion number. The following values . 


are allowed: 
Value Sample Data Item Meaning 
0 CS-CHARACTER-SET-V Coded character set number 
1 CS-CCSVERSION-V Ccsversion number 


NUM is passed by reference to the procedure. It contains the number of the coded 
character set or ccsversion for which the name is being requested. If you supply the 
value —2 in the NUM parameter when you are checking a ccsversion, the procedure 
returns the name of the system default ccsversion. Refer to the MLS Guide for more 
information about the hierarchy. 


NAME-ARY is returned by the procedure. It contains the coded character set or 
ccsversion name. The recommended length of the name is 17 characters. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by VALIDATE NUM_RETURN_NAME are as follows: 


1 , | 3000 3006 
1001 3001 
1002 3003 


Sample output from Example 16-24 follows: 


RESULT = 1 
NAME-ARY = CANADAGP 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 
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VSNCOMPARE_TEXT 


16-98 


This procedure compares two records, using one of three comparison methods. The 
comparison is specified as one of the following types: 


e A binary comparison, which is based on the hexadecimal code values of the 
characters 


e An equivalent comparison, which is based on the ordering sequence values (OSVs) of 
the characters | 


e A logical comparison, which is based on the ordering sequence values (OSVs) plus 
the priority sequence values (PSVs) of the characters 


The procedure retrieves the OSVs and PSVs from the file SYSTEM/CCSFILE based on 
the specified ccsversion. 


Example 


Example 16-25 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the VSNCOMPARE TEXT library procedure. The declarations 
identify the category of data-item required for parameter matching. For example, 
numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example compares two strings using the CanadaEBCDIC eesversion. The first 
string is “hotel” and the second string is “Hotel.” Assume the following ordering values 
for the characters: 


Ordering Sequence Value Priority Sequence Value 

Character (OSV) (PSV) 

e 69 2 

h 72 2 

| 76 2 

fo) 79 2 

t | 84 2 
% 79 8. 


The compare relation is CsCmpEq] (=) to determine if “hotel” is equal to “Hotel” using 
a logical comparison. You can use the MLS Guide to determine that the cesversion © 
number for CanadaEBCDIC is 74. You can also retrieve this number by calling the 
procedure VALIDATE NAME _RETURN_NUM with the name CanadaEBCDIC. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 


INPUT-OUTPUT SECTION. 
FILE-CONTROL. 


Example 16-25. Calling the VSNCOMPARE_TEXT Procedure | 
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SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OQUTPUT-FILE 
~ LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "OUT/COBOL74/VSNCOMPARETEXT." 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


@1 OF-1. 
05 FILLER PIC X(@9) = VALUE "RESULT = ". 
05 OF-RESULT PIC ZZZ222222229. 
65 FILLER PIC X(59) | VALUE SPACE. 


KREKKREKKEERERERRREERKEREKRERERERRREREEREKKKREEERKREREREREREKEEKERERKEKKK 


#e*° The following global declarations are used as parameters *** 


*** to the CENTRALSUPPORT procedures. aaa 
KRKKKEKKEEEREREKKRERERERKEEKRKREKKEKKKREERREKERERRERRERKRRERERRERREKEEKEER 
@1 TEXT1-TEXT PIC X(@5). 

G1 TEXT2-TEXT PIC X(@5). 

77 CS-CMPEQLV PIC $9(11) USAGE BINARY VALUE 2. 

77 CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 

77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 

77 CS-LOGICALV | PIC $9(11) USAGE BINARY VALUE 2. 

77 ~TEXT1-START PIC $9(11) USAGE BINARY. 

77 TEXT2-START PIC $9(11) USAGE BINARY. 

77 COMPARE-LEN PIC $9(11) USAGE BINARY. 

77 RESULT PIC $9({11) USAGE BINARY. 

77 VSN-NUM PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM VSNCOMPARE-TEXT. 
CLOSE OUTPUT-FILE. 
STOP RUN. ~ 


KkRKK VSNCOMPARE-TEXT KEKKEKKEKEKEKEKEKREEEREERKEKEERERERKEREREREEERE 


VSNCOMPARE-TEXT. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE 74 TO VSN-NUM. 
MOVE 5 TO COMPARE-LEN. 
MOVE "hotel" TO TEXT1-TEXT. 


Example 16-25. Calling the VSNCOMPARE_TEXT Procedure (cont.) 
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16-100 


MOVE "hétel" TO TEXT2-TEXT. 
CALL "VSNCOMPARE_TEXT OF CENTRALSUPPORT" 
USING VSN-NUM, 
TEXT1-TEXT, 
TEXT1-START, 
TEXT2-TEXT, 
TEXT2-START, 
COMPARE-LEN, 
CS-CMPEQLV, 
CS-LOGICALV 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE QUTPUT-RECORD FROM OF-1. 


Example 16-25. Calling the VSNCOMPARE_TEXT Procedure (cont.) 


Explanation . 


VSN-NUM is passed to the procedure. It contains the number of the ccsversion that is 
used to compare the text records. The number can be obtained by referring to the MLS 
Guide. The following values are allowed: 


Value Meaning 


Greater than or Designate a ccsversion. 
equal to 0 (zero) 


-2 , Use the system default ccsversion. If the system default ccsversion is not 
available, the procedure returns an error in RESULT. 


TEXT1-TEXT is passed to the procedure. It contains the first record of text to be 
compared. You determine the size of the record. 


TEXT1-START is passed by reference to the procedure. It contains the byte offset in 
TEXT1-TEXT, relative to 0 (zero), at which the comparison begins. 


TEXT2-TEXT is passed to the procedure. It contains the second record of text to be 
compared. You determine the size of the record. 


TEXT2-START is passed to the procedure. It contains the byte offset in TEXT2-TEXT, 
relative to 0 (zero), at which the comparison begins. 


COMPARE-LEN is passed by reference to the procedure. It contains the number of 
characters to compare. If COMPARE-LEN is larger than the number of characters 
in the strings, then the procedure might be comparing invalid data. The value 

of COMPARE-LEN should not exceed the bounds of either TEXT1-TEXT or 
TEXT2-TEXT. 


The strings should be of equal size or padded with blanks up to the value of 
COMPARE-LEN. If all pairs of characters compare equally, the strings are considered 
equal. Otherwise, the first pair of unequal characters encountered is compared to 
determine their relative ordering. The string that contains the character with the higher 
ordering (higher PSV and higher OSV) is considered to be the string with the greater 
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value. If substitution forms strings of unequal length, the comparison proceeds as if the 
shorter string were padded with blanks on the right. This paceing ensures that the 
strings are of equal length. 


CS-CMPEQLV is passed by reference to the procedure. It indicates the relational 
operator of the comparison. The valid values are 


Value Sample Value Name Meaning 

0 CS-CMPLSSV TEXT1-TEXT is less than TEXT2-TEXT. 

1 CS-CMPLEQV . .  TEXT1-TEXT is less than or equal to 
TEXT2-TEXT. 

2 CS-CMPEQLV TEXT1-TEXT is equal to TEXT2-TEXT. 

3 CS-CMPGTRV __ TEXT1-TEXT is greater than TEXT2-TEXT. 

4 CS-CMPGEQV TEXT1-TEXT is greater than or equal to 
TEXT2-TEXT. 

5 CS-CMPNEQV TEXT1-TEXT is not equal to TEXT2-TEXT. 


CS-LOGICALV is passed by reference to the procedure. It indicates the type of 
comparison to be performed by the procedure. The following are the valid values: 


Value Sample Value Name Meaning 
0 BINARY-V Perform a binary comparison 
1 EQUIVALENT-V Perform an equivalent comparison 
2: LOGICAL-V Perform a logical comparison 


RESULT is returned as the value of the procedure. It contains the procedure result or 
indicates that an error occurred during the execution of the procedure. The possible 
values for RESULT and their meanings are as follows: 


Value Condition-Name Meaning 
0 CS-FALSEV No error and the condition is FALSE 
1 . CS-DATAOKV No error and the condition is TRUE 


Other possible values returned by the procedure are as follows: 
1000 1002 3006 
1001 3003 


The meanings of the error result values are explained at the end of this section. 
Sample output from Example 16-25 follows: 


RESULT. = B 


See Also 


For more information on the error result values, see Table 16—2 later in this section. 
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VSNESCAPEMENT 


16-102 


This procedure takes the input text and rearranges it according to the escapement 

rules of the ccsversion. Both the character advance direction and the character 
escapement direction are used. If the character advance direction is positive, then 

the starting position for the escapement process is the leftmost position of the text in 
the DEST-TEXT parameter. If the character advance direction is negative, then the 
starting position for the escapement process is the rightmost position of the text in the 
DEST-TEXT parameter. From that point on, the character advance direction value and 
the character escapement direction values, in combination, control where each character 
should be placed in relation to the previous character. 


_ Example 


Example 16-26 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the VSNESCAPEMENT library procedure. The declarations 
identify the category of data-item required for parameter matching. For example, 
numeric items must be declared PIC $9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example takes the string ABCDEFG and rearranges it according to the escapement 
rules of the ccsversion. Assume for this example a ccsversion number of 999 with a 
character advance direction of plus (+, left to right) and with the following character . 
escapements: ; 


Character Escapement Meaning 

A + Left to right. 

B - Right to left. 

C - Right to left. 

D - Right to left. 

E + Left to right. 

F + . Left to right. 

G blank Use character advance direction value. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 


FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 


Example 16-26. Calling the VSNESCAPEMENT Procedure 
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VALUE OF TITLE IS "OUT/COBOL74/VSNESCAPEMENT." 
PROTECTION SAVE 

RECORD CONTAINS 8@ CHARACTERS 

DATA RECORD IS OUTPUT-RECORD. 


81 OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


@1 OF-1. 
@5 FILLER PIC X(69) VALUE "RESULT = ". 
@5 OF-RESULT PIC ZZ2ZZZZZZ2229. 
@5 FILLER PIC X(59) | VALUE SPACE. 
@1 OF-2. 
@5 FILLER PIC X(12) VALUE "DEST-TEXT = ". 
@5 OF-DEST-TEXT. PIC X(@7). 
@5 FILLER PIC X(61) | VALUE SPACE. 


KREERERKEKRKERERKERERERREERKKEEKEKERERERREERKERERKKRREREKRERKEKEKRRKKKKKKKEKKKK 


*x** The following global declarations are used as parameters *** 


*** to the CENTRALSUPPORT procedures. sas 
HRKKKEREKRERKERRERRKREREREERER EERE RERER EERE EER ERE EER EREEEERERERERERERE 
@1 DEST-TEXT PIC X(@7). 

81 SOURCE-TEXT PIC X(@7). 

77 CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 

77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE 9. 

77 =SOURCE-START PIC $9(11) USAGE BINARY. 

77 TRANS-LEN PIC $9(11) USAGE BINARY. 

77 RESULT PIC $9(11) USAGE BINARY. 

77 VSN-NUM PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM VSNESCAPEMENT. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


kKkKKK VSNESCAPEMENT KEKKEKKEREKEKEEKRKEREKREREEKKEEREEKEEERKREKEREERKEE 


VSNESCAPEMENT. 
CHANGE ATTRIBUTE LIBACCESS OF "“CENTRALSUPPORT" TO BYFUNCTION. 
MOVE 999 TO VSN-NUM. . 
MOVE "ABCDEFG" TO SOURCE-TEXT. 
_ MOVE 7 TO TRANS-LEN. 
CALL "VSNESCAPEMENT OF CENTRALSUPPORT" 
USING VSN-NUM, 
SOURCE-TEXT, 
SOURCE-START, 
DEST-TEXT, 


Example 16-26. Calling the VSNESCAPEMENT Procedure (cont.) 
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TRANS-LEN 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE DEST-TEXT TO OF-DEST-TEXT 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-26. Calling the VSNESCAPEMENT Procedure (cont.) 


Explanation 


VSN-NUM is passed by reference to the procedure. It specifies the ccsversion to be 
used. The cesversion contains the escapement rules. The following are the values 


allowed for VSN-NUM: 
Value. Meaning 
Greater than or Specifies a ccsversion. The numbers of the ccsversions are listed in the 
equal to 0 MLS Guide. 
-2 Specifies the system default cesversion. if the system default 


ccsversion is not available, an error is returned. 


SOURCE-TEXT is passed to the procedure. It contains the text to be arranged 
according to the escapement rules. You must determine the size of the record. 


SOURCE-START is passed by reference to the procedure. It specifies where in 
SOURCE-TEXT the procedure is to begin rearranging the text. 


DEST-TEXT is returned by the procedure. It contains the rearranged text. The length 
of the SOURCE-TEXT parameter and the DEST-TEXT parameter should be the same. 


- TRANS-LEN is passed by reference to the procedure. It specifies the number of 
characters to rearrange, beginning at SOURCE-START. 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by the procedure are as follows: 


1 - 1002 3003 
1000 3000 
1001 | 3002 
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Sample output from Example 16-26 follows: 
RESULT = ae 
DEST-TEXT = ADCBEFG 


See Also 


For more information on the error result values, see Table 16—2 later in this section. 


VSNGETORDERINGFOR_ONE_TEXT 


This procedure returns the ordering information for a specified input text. The ordering 
information determines how the input text is collated. It includes the ordering sequence 
values (OSVs) and optionally the priority sequence values (PSVs) of the characters. It 
always includes any substitution of characters to be made when the input text is sorted. 
You can choose one of the following types of ordering information: 


Type of Ordering Explanation 
Equivalent The DEST parameter consists of a sequence of OSVs. 
Logical | The DEST parameters consists of a sequences of OSVs 


followed by PSVs. 


Example 

Example 16-27 shows the parameter declarations and the PROCEDURE DIVISION 

syntax required to call the VSNGETORDERINGFOR_ONE_TEXT library procedure. 
The declarations identify the category of data-item required for parameter matching. 

For example, numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example obtains the OSVs and PSVs for the input text string “ABC.” The 
ecsversion is CanadaEBCDIC. You can use the MLS Guide to determine that the 
cesversion for CanadaEBCDIC is 74. You can also retrieve this number by calling the 
procedure VALIDATE NAME RETURN_NUM with the name CanadaEBCDIC. 

This example requests logical ordering information, so both the OSVs and PSVs are 
returned. This example also allows for maximum substitution, so the parameter 
max_osvs is equal to itext_len * 3 and the parameter total_storage is equal to max_osus 
+ round(max.. osus/2.0). 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
. SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD QUTPUT-FILE 


Example 16-27. Calling the VSNGETORDERINGFOR_ONE_TEXT Procedure 
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G1 


LABEL RECORD IS STANDARD 


VALUE OF TITLE IS "OUT/COBOL74/VSNGETORDONETEXT." 


PROTECTION SAVE 
RECORD CONTAINS 8@ CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


OUTPUT-RECORD PIC X(8@). 


WORKING-STORAGE SECTION. 


G1 


G1 


VALUE "RESULT = ". 


VALUE 


SPACE. 


VALUE "DEST-TEXT = ". 


VALUE 


SPACE. 


KKEKREKRKEEKREKREREKEEKEKEEEKREEKEKRKRERERREERERRERERREEREEEEERRERERKEREKRE 


kkk 


KKK 


The following global declarations are used as parameters *** 


kkk 


KEEKKEREKKEKEEKEERKEKEREKREREEKEERERERERREKRERERRRRERERERERERERERREEERRE 


G1 
G1 


77 
77 


USAGE 


_ USAGE 


USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 


OF-1. 

@5 FILLER PIC X(@9) 
@5 OF-RESULT PIC ZZZZZZZZZZZ9. 
@5 FILLER PIC X(59) 
OF-2. 

®5 FILLER PIC X(12) 
@5 OF-DEST-TEXT PIC X(51). 
®5 FILLER PIC X(17) 
to the CENTRALSUPPORT procedures. 
DEST-TEXT PIC X(51). 
SOURCE-TEXT PIC X(51). 
CS-DATAOKV | PIC $9(11) 
CS-FALSEV PIC $9(11) 
CS-LOGICALV PIC $9(11) 
DEST-START PIC $9(11) 
ITEXT-LEN PIC $9(11) 
MAX-OSVS PIC $9(11) 
RESULT PIC $9(11) 
SOURCE-START PIC $9(11) 
TOTAL-STORAGE PIC $9(11) 
VSN-NUM PIC $9(11) 


PROCEDURE DIVISION. 


IN 


TLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 


PERFORM VSNGETORDERINGFOR-ONE-TEXT. 


CLOSE OUTPUT-FILE. 
STOP RUN. 


USAGE 


BINARY 
BINARY 


BINARY 


BINARY. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 


BINARY. ~ 


BINARY. 


VALUE 1. 
VALUE @. 
VALUE 2. 


*kkKK VSNGETORDERINGFOR-ONE-TEXT **#X#RRRARRI ARIA AKIRA RRR IRRIRIR 
VSNGETORDERINGFOR-ONE-TEXT. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 


MOVE 74 TO VSN-NUM. 
MOVE 5 TO ITEXT-LEN. 
COMPUTE MAX-OSVS = ITEXT-LEN * 3. 


Example 16-27. Calling the VSNGETORDERINGFOR_ONE_TEXT Procedure (cont.) 
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COMPUTE TOTAL-STORAGE = MAX-OSVS + MAX-OSVS / 2. 
MOVE "ABCzeAS" TO SOURCE-TEXT. 
CALL "VSNGETORDERINGFOR_ONE_TEXT OF CENTRALSUPPORT" 
USING VSN-NUM, 
SOURCE-TEXT, 
SOURCE-START, 
ITEXT-LEN, 
DEST-TEXT, 
DEST-START, 
MAX-OSVS, 
TOTAL-STORAGE, 
CS-LOGICALV 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE DEST-TEXT TO OF-DEST-TEXT 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-27. Calling the VSNGETORDERINGFOR_ONE TEXT Procedure (cont.) 


Explanation 


VSN-NUM is passed to the procedure. It contains the number of the ccsversion that is 
used. The number can be obtained by calling the CENTRALSTATUS procedure or by 
referring to the MLS Guide. The following shows the allowed values: 


Value Meaning 

Greater than or Specifies a ccsversion. The numbers of the ccsversions are listed in the 
equal to O MLS Guide. . 

-2 Use the system default ccsversion. If the system default ccsversion is 


not available, an error is returned. 


SOURCE-TEXT is a record passed to the procedure. It contains the text for which the 
ordering information is requested. 


SOURCE-START is passed by reference to the procedure. It contains the offset of the 
location where the translation is to begin. 


ITEXT-LEN is eased by reference to the procedure. It contains the length of the text 
that is to be translated. 


DEST-TEXT i is a record returned by the Siaesdane: It contains the ordering information 
for the input text. 


DEST-START i is returned by the procedure. It designates the starting offset at which 
the result values are placed. 


MAX-OSVS is an integer passed by reference to the procedure. It designates the 
maximum number of storage bytes to be used to store the ordering sequence values. 
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The value of MAX-OSVS should be the length of the input text. In the case when 
substitution is required, the MAX-OSVS value might need to be more than the length - 
of the input text. The maximum substitution length defined for any ccsversion is 3; 
therefore, to allow for substitution for every character, the value of MAX-OSVS is as 
follows: 


(length of source text in bytes) * 3 


If the number of OSVs returned is less than MAX-OSVS, then the alphanumeric record 
is packed with the ordering sequence value for blank. 


TOTAL-STORAGE is passed by reference to the procedure. It defines the maximum 
number of bytes needed to store the complete ordering information for the text. If you 


~ request equivalent ordering information, TOTAL-STORAGE and MAX-OSVS should 


be set the same. If you request logical ordering information, you must provide space for 
the four-bit priority values in addition to the space allowed for the OSVs. Each OSV © 
has one PSV, and one byte can hold two PSVs. Therefore, the space allowed for PSVs 
MAX-OSVS/2, and the value of TOTAL-STORAGE should be set as follows: 


MAX-OSVS + (MAX-OSVS) /2 


When the ordering information is returned by the procedure, all the OSVs are listed | 
first, followed by all the PSVs. 


CS-LOGICALV is an integer passed by reference to the procedure. It indicates the type 
of ordering information you want, as follows: 


Value Sample Value Name _ Meaning 
1 CS-EQUIVALENTV OSVs only 
2 CS-LOGICALV . PSVs only 


RESULT is returned as the value of the procedure. It indicates whether an error 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by this procedure are as follows: 


0 1002 3003 

1 - 3000 3006 
1000 | 3001 3008 
1001. 3002 


Sample output from Example 16-27 follows: 


RESULT = CS_DATAOKV 
DEST-TEXT = 414243414541 454646494949 494949111221 111111111111 


Based on the values of DEST-TEXT, the OSVs are 65, 66, 67, 65, 69, 65, and 69. The 
PSVs are 1, 1, 1, 2,2, 1, and 1. 
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See Also 


For more information on the error result values, see Table 16-2 later in this section. 


VSNINSPECT_TEXT 


This procedure searches a specified text for characters that are present or not present 
in a requested data class. The SCANNED-CHARS parameter is an integer that 
represents the number of characters that were searched when the criteria specified 

in the CS_ NOT_INTSETV parameter were met. If SCANNED-CHARS is equal to 
INSPECT-LEN, then all the characters were searched but none met the criteria. 
Otherwise, adding the TEXT-START value to the RESULT value gives the location of 
the character, from the start of the array, that met the search criteria. 


Example 


Example 16-28 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the VSNINSPECT_TEXT library procedure. The declarations 

. identify the category of data-item required for parameter matching. For example, 
numeric items must be declared PIC $9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example examines a record that contains two fields, a name and a phone number. 
The name is verified to contain only alphabetic characters as defined by the France 
_ cesversion. You can use the MLS Guide to determine that the ccsversion number for 
France is 35. You can also retrieve this number by calling the procedure CCSVSNNUM 
with the name France. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS “OUT/COBOL74/VSNINSPECTTEXT. . 
PROTECTION SAVE 
RECORD CONTAINS 8 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


@1 OUTPUT-RECORD © PIC X(8@). 
WORKING-STORAGE SECTION. 


Example 16-28. Calling the VSNINSPECT_ TEXT Procedure 
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@1 OF-1. a 
@5 FILLER — PIC X(@9) VALUE "RESULT = ". 
@5 OF-RESULT PIC ZZZZZZZ22229. 
, @5 FILLER PIC X(59) | VALUE SPACE. 
G1 OF-2. 
@5 FILLER PIC X(16) | VALUE "SCANNED-CHARS = “. 
@5 OF-SCANNED-CHARS PIC ZZZZZZZZ2229. 


@5 FILLER PIC X(52) VALUE SPACE. 


KRREKKKERKEKRERRKEERERERERKEEKRREEREEREREKREREKREREREREKRERREERERRERKRKERERK 


*** The following global declarations are'used as parameters *** 


*** to the CENTRALSUPPORT procedures. ad 
KERKREKRKKREEEKEKEKERREREEEREKRRRERKEKEERKEREREREKEREREREREKEREKKKKRKKK 
81 SOURCE-TEXT PIC X(41). 

77 CS-DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 

77 CS-FALSEV PIC S$9(11) USAGE BINARY VALUE 9. 

77 CS-NOT-INTSETV PIC S$9(11) USAGE BINARY VALUE @. 

77 CS-NUMERICSV PIC $9(11) USAGE BINARY VALUE 13. 

77 ~=ID-LEN PIC $9(11) USAGE BINARY VALUE 18. 

77 INSPECT-LEN PIC $9(11) USAGE BINARY. 

77 NAME-LEN PIC S$9(11) USAGE BINARY VALUE 38. 

77 SCANNED-CHARS PIC $9(11) USAGE BINARY. 

77 SOURCE-START PIC $9(11) USAGE BINARY. 

77 RESULT PIC $9(11) USAGE BINARY. 

77 VSN-NUM PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM VSNINSPECT-TEXT. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


kkk VSNINSPECT-TEXT KERKEKKKEKKKEKEREKERKERKEEREKRKREERERREERKKREREKEE 


VSNINSPECT-TEXT. 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE 35 TO VSN-NUM. 
MOVE NAME-LEN TO INSPECT-LEN. | 
MOVE "7775961989John Alan Smith " TO SOURCE-TEXT. 
CALL "VSNINSPECT_TEXT OF CENTRALSUPPORT" 
USING VSN-NUM, 
SOURCE-TEXT, 
SOURCE-START, 
INSPECT-LEN, 
CS-NUMERICSV, 
CS-NOT-INTSETV, 
SCANNED-CHARS _ 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 


Example 16-28. Calling the VSNINSPECT_TEXT Procedure (cont.) 
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- WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV AND 
SCANNED=-CHARS IS EQUAL TO ID-LEN 
THEN MOVE SCANNED-CHARS TO OF-SCANNED-CHARS 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-28. Calling the VSNINSPECT_TEXT Procedure (cont.) 


Explanation 


VSN-NUM is passed by reference to the procedure. It specifies the ccsversion to be 
used. The ccsversion contains the rules for applying a truthset. The following are the 


values allowed for VSN-NUM: 
Value Meaning 
Greater than or Specifies a ccsversion. The numbers of the ccsversions are listed in the 
equal to 0 MLS Guide. 
-2 - Specifies the system default ccsversion. If the system default 


ccesversion is not available, an error is returned. 


SOURCE-TEXT is passed to the procedure. The record is searched for a character using 
the requested truthset and type of search. You determine the size of the record. 


SOURCE-START is passed by reference to the procedure. It contains the byte offset in 
SOURCE-TEXT, relative to 0 (zero), at which the search begins. 


ID-LEN is passed by reference to the procedure. It specifies the length of the inspected 
test; that is, the number of characters found to be numeric. 


INSPECT-LEN is passed by reference to the procedure. It specifies the number of | 
characters to be searched beginning at SOURCE-START It specifies that maximum 
length of the search. 


NAME-LEN passed by reference to the procedure. It specifies the length of the name to 
be inspected. 


CS-NUMERICSV is passed to the procedure. It indicates the type of truthset to be used 
for the search. The following are the values allowed for CS-NUMERICSV and their 


meanings: 
Value Sample Data Name Meaning 
12 CS-ALPHAV Alphabetic truthset. It identifies the characters 
defined as alphabetic in the specified ccsversion. 
13 CS-NUMERICSV Numeric truthset. It identifies the characters 
defined as numeric in the specified ccsversion. 
14 CS-PRESENTATIONV Presentation truthset. It identifies the characters in 


the ccsversion that can be represented on a 
presentation device, such as a printer. 


15 CS-SPACESV Spaces truthset. It identifies the characters defined 
as spaces in the specified ccsversion. 


continued 
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continued 
Value Sample Data Name Meaning 

16 CS-LOWERCASEV Lowercase truthset. It identifies the characters 
defined as lowercase alphabetic in the specified 
ccsversion. 

17 CS-UPPERCASEV Uppercase truthset. it identifies the characters 
defined as uppercase alphabetic in the specified 
ccsversion. 


A cesversion is not required to have a definition for each of these truthsets. Some of the 
truthsets, such as 16 and 17, are optional. A result of 4002 might be returned if the 
truthset was not defined for the ccsversion. The input text remains unchanged. 


CS-NOT-INSETV is passed to the procedure. It indicates the type of search to be 
performed. The values allowed for this parameter and their meanings are as follows: 


Value Sample Data Name Meaning 


0 CS-NOTINTSETV Search the text until a character is found that is 
not in the requested truthset. 


1 CS-INTSETV Search the text until! a character is found that isin — 
, the requested truthset. 


SCANNED-CHARS is an integer returned by the procedure. It contains the number of | 
characters, relative to0 (zero), that. were scanned when the search criteria was met. 


RESULT is returned as the value of the procedure. It indicates whether anerror _ 
occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by VSNINSPECT_TEXT are as follows 


1 3000 3007 
1000 3001 4002 
1001 3003 | 
1002 3006 


Sample output from Example 16-28 follows: 


RESULT = 1 
SCANNED-CHARS = 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 
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VSNTRANS_TEXT 


This procedure applies a specified mapping table to the source text and places the result 
into the destination parameter. You can use the same record for both the source and 
destination text. 


You might use this procedure to translate alternative digits received as data into numeric 
digits for arithmetic processing. 


Example 


Example 16-29 shows the parameter declarations and the PROCEDURE DIVISION 
syntax required to call the VSNTRANS_TEXT library procedure. The declarations 
identify the category of data-item required for parameter matching. For example, 
numeric items must be declared PIC S9(11) USAGE BINARY. 


In the explanation following the example, the parameters are explained using the names 
given to them in the example. In your program, choose parameter names that are 
appropriate for your use. 


This example translates a string in lowercase letters to uppercase letters using the 
CanadaEBCDIC ccsversion. The input string is “pzean.” You can use the MLS Guide to 
determine that the ccsversion number for CanadaEBCDIC is 74. You can also retrieve 
this number by calling the procedure CCSVSNNUM with the name CanadaEBCDIC. 


IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OUTPUT-FILE ASSIGN TO DISK. 


DATA DIVISION. 
FILE SECTION. 
FD OUTPUT-FILE 
LABEL RECORD IS STANDARD 
VALUE OF TITLE IS "OUT/COBOL74/VSNTRANSTEXT." 
PROTECTION SAVE 
RECORD CONTAINS 88 CHARACTERS 
DATA RECORD IS OUTPUT-RECORD. 


G1 OUTPUT-RECORD PIC X(88). 


WORKING-STORAGE SECTION. 


G1 OF-1. 
@5 FILLER PIC X(@9) VALUE "RESULT = ". 
95 OF-RESULT PIC ZZZ2ZZZ22ZZZ7Z9. 
@5 FILLER PIC X(59) | VALUE SPACE. 
G1 OF-2. . 
@5 FILLER PIC X(12) VALUE "DEST-TEXT = ". 


95 OF-DEST-TEXT PIC X(@7). 


Exampte 16-29. Calling the VSNTRANS TEXT Procedure 
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@5 FILLER PIC X(61) | VALUE SPACE. 


KEKKRKRKRKEKEKEKREREKRERERKREREREKREREERREREREREREERREERKEERKKREKERRERERRERKEE 


*** The following global declarations are used as parameters *** 
*** to the CENTRALSUPPORT procedures. died 


KKEKKEKRKKEKERERKEKERKRKEKEREREREKRKERERERERKERREREKREERRREKREEREKRRERKRERE 


G1 DEST-TEXT PIC X(@7). 

G1 SOURCE-TEXT PIC X(97). 
77° CS=DATAOKV PIC $9(11) USAGE BINARY VALUE 1. 
77 CS-FALSEV PIC $9(11) USAGE BINARY VALUE @. 
77 CS=-LOWTOUPCASEV PIC $9(11) USAGE BINARY VALUE 7. 
77 ~DEST-START PIC $9(11) USAGE BINARY. 

77 SOURCE-START PIC S$9(11) USAGE BINARY. 

77 RESULT ' PIC $9(11) USAGE BINARY. 

77 TRANS-LEN PIC $9(11) USAGE BINARY. 

77 VSN-NUM PIC $9(11) USAGE BINARY. 


PROCEDURE DIVISION. 
INTLCOBOL74. 
OPEN OUTPUT OUTPUT-FILE. 
PERFORM VSNTRANS-TEXT. 
CLOSE OUTPUT-FILE. 
STOP RUN. 


KKKKE VSNTRANS-TEXT KKEKKRKEKEERERERKEKEREREERREREKREREREKERREEK 


VSNTRANS-TEXT. | | 
CHANGE ATTRIBUTE LIBACCESS OF "CENTRALSUPPORT" TO BYFUNCTION. 
MOVE 74 TO VSN-NUM. 
MOVE 4 TO TRANS-LEN. 
MOVE "pean" TO SOURCE-TEXT. 
CALL "VSNTRANS TEXT OF CENTRALSUPPORT" 
USING VSN-NUM, 
SOURCE-TEXT, 
SOURCE-START, 
DEST-TEXT, 
DEST-START, 
TRANS~-LEN, 
CS-LOWTOUPCASEV 
GIVING RESULT. 
MOVE RESULT TO OF-RESULT. 
WRITE OUTPUT-RECORD FROM OF-1. 
IF RESULT IS EQUAL TO CS-DATAOKV 
THEN MOVE DEST-TEXT TO OF-DEST-TEXT. 
WRITE OUTPUT-RECORD FROM OF-2. 


Example 16-29. Calling the VSNTRANS_TEXT Procedure (cont.) 
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Explanation 


VSN-NUM is an integer passed by reference to the procedure. It contains the number 
of the ccsversion to be used. The ccsversion contains the rules for translation of text. 
Refer to the MLS Guide for a list of the ccsversion numbers. The values allowed for 
VSNNUM and the meanings of the values are as follows: 


Value Meaning 
Greater than or equal to 0 Use the specified ccsversion number. 
-2 Use the system default ccsversion. If the system default 


ccsversion is not available, an error is returned. 


SOURCE-TEXT is passed to the procedure. It contains the data to translate. You 
should determine the size of this record. 


SOURCE-START is passed to the procedure. It designates the byte offset, relative to 0 
(zero), in SOURCE-TEXT at which translation is to begin. 


DEST-TEXT is returned by the procedure. It contains the translated text. This record 
and the record in the SOURCE-TEXT parameter should be the same size. 


DEST-START is passed to the procedure. It indicates the offset in the DEST-TEXT 
parameter where the translated text is to be placed. 


TRANS-LEN is passed to the procedure. It designates the number of characters in the 
SOURCE-TEXT parameter to translate, beginning at SOURCE-START. 


CS-LOWTOUPCASEYV is passed to the procedure. It designates the type of translation 
requested. The allowed values for CS-LOWTOUPCASEV and their meanings are as 


follows: 
Value Sample Data Name Meaning 
5 CS-NUMTOALTDIGV Translate numbers 0 through 9 to alternate 
digits specified in the ccsversion. 
-6 CS-ALTDIGTONUMV Translate alternate digits to numbers O through 
a 9. 
73 CS-LOWTOUPCASEV Translate all characters from lowercase to 
uppercase. 
8 CS-UPTOLOWCASEV Translate all character from uppercase to 
lowercase. 
9 CS-ESCMENTPERCHARV - Translate a character to its escapement value. 


A ccsversion is not required to have a definition for each of these tables. Some of the 
tables, such as 5, 6, 7, and 8, are optional. A result of 4002 might be returned if the table 
was not defined for the ccsversion. The input text remains unchanged. . 


RESULT is returned as the value of the procedure. It indicates whether an error: 


occurred during the execution of the procedure. Values greater than or equal to 1000 
indicate an error. An explanation of the error result values can be found at the end of 
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this section. You should check the procedure result whenever you use this procedure. 
Possible values returned by VSNTRANS_TEXT are as follows: 


1 3000 3006 
1000 3001 4002 
1001 3002 
1002 3003 


Sample output from Example 16-29 follows: 


RESULT = 1 
DEST-TEXT = PAGAN 


See Also 


For more information on the error result values, see Table 16-2 later in this section. 


Errors 


All of the procedures in the CENTRALSUPPORT library return integer results to 
indicate the success or failure of the procedure. 


Declarations 


Example 16-30 shows a sample set of declarations for the message values. 


@1 ERROR-VALUES PIC $9(11) USAGE BINARY. 
88 CS-FILE-ACCESS-ERRORV VALUE 1989. 
88 CS-FAULTV VALUE 1981. 
88 CS-SOFTERRV VALUE 1982. 
88 LANGUAGE-NOT-FOUNDV VALUE 2601. 
88 CONVENTION-NOT-FOUNDV VALUE 2082. 
88 FLD-TRUNCATEDV | VALUE 2083. 
88 INCOMPLETE-DATAV VALUE 2004. 
88 BAD-ARRAY-DESCRIPTIONV VALUE 3808. 
88 ARRAY-TOO-SMALLV VALUE 3801. 
88 BAD-DATA-LENV VALUE 3882. 
88 NO-NUM-FOUNDV VALUE 3893. 
88 NO-NAME-FOUNDV VALUE 3884. 
88 NO-MSGNUM-FOUNDV VALUE 38085. 
88 BAD-TYPE-CODEV VALUE 3806. 
88 BAD-FLAGV VALUE 3887. 
88 BAD-TEXT-PARAMV VALUE 30088. 
88 BAD-TEMPCHARV VALUE 3811. 
88 BAD-DATEINPUTV VALUE 3812. 
88 . BAD-TIMEINPUTV VALUE 3013. 
88 CNV-EXISTS-ERRV VALUE 3814. 


88 BAD-MAXDIGITSV VALUE 3815. 


y 


Example 16-30. Declaring Message Values 
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88 BAD-FRACDIGITSV VALUE 3016. — 
88 BAD-ALTFRACDIGITSV VALUE 3817. 
88 BAD-LDATETEMPV VALUE 3818. 
88 BAD-SDATETEMPV VALUE 3819. 
88 BAD-NDATETEMPV VALUE 3029. 
88 BAD-LTIMETEMPV VALUE 3821. 
88 BAD-NTIMETEMPV VALUE 3822. 
88 BAD-MONTEMPV : VALUE 3823. 
88 BAD-NUMTEMPV - VALUE 3924. 
88 BAD-LPPV VALUE 3827. 
88 BAD-CPLV VALUE 3828. 
88 REQSYMBOLV VALUE 3929. 
88 BAD-TEMPLENV VALUE 3039. 
88 MUTUAL-EXCLUSIVEV VALUE 3931. 
88 BAD-MINDIGITSV VALUE 39832. 
88 MISSING-RBRACKETV VALUE 3833. 
88 MISSING-TCCOLONV VALUE 3034. 
88 BAD-INPUTVALV VALUE 3835. 
88 CNV-NOTAVAILV VALUE 3936. 
88 CNVFILE-NOTPRESENTV VALUE 3837. 
88 BAD-PRECISIONV VALUE 3838. 
88 NO-CNVNAMEV ; VALUE 3839. 
88 DEL-PERMANENTCNV-ERRV VALUE 3049. 
88 NO-HEXCODE-DELIMV VALUE 30841. 
88 BAD-HEXCODEV VALUE 3942. 
88 NO-ALTCURR-DELIMV VALUE 3043. 
88 DATA-NOT-FOUNDV VALUE 4882. 


Example 16-30. Declaring Message Values (cont.) 


Explanation of Error Values 
The range 1000 through 1999 are error messages that report a Unisys software error. 


Values from 2000 through 2999 contain error messages in which the caller passed invalid 
data to a procedure, but the CENTRALSUPPORT library was able to return some valid 
data. 


Values from 3000 through 3999 contain error messages in which the caller passed invalid 
data toa CENTRALSUPPORT procedure, and the CENTRALSUPPORT library was 
unable to return any valid data. 


Values from 4000 through 4999 contain error messages in which the caller passed some 
sort of data for which the CENTRALSUPPORT library could find no return information. 
CENTRALSUPPORT completed the request, but no data was returned. 


Table 16—2 lists the error numbers that can be returned for internationalization and the 
specific descriptions of the error messages that you can have your program display. 
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| See Also 


e Refer to GET_CS_ MSG earlier in this section for information about the message 
parts. 


e Refer to the MLS Guide for a list of the complete error messages and for 
information about the corrective actions to be taken if an error occurs. 


Table 16-2. Specific Descriptions for Internationalization Error Values 


Error Value Specific Description 


An error. occurred while accessing the SYSTEM/CCSFILE or the 
SYSTEM/CONVENTIONS file. 


An unexpected fault occurred in CENTRALSUPPORT. Your request cannot be 
processed at this time. 


A CENTRALSUPPORT software error was detected. Your request cannot be 
processed at this time. 


The data is not in the requested language. It is in MYSELF.LANGUAGE or the 
SYSTEM LANGUAGE or the first available LANGUAGE. 


The data is not in the requested convention; it is in MYSELF.CONVENTION or 
the SYSTEM CONVENTION. 


The DATE or TIME component was too long and was truncated. 


Only partial data is being returned. There was insufficient space in the output 
array. 


A parameter was incorrectly specified as less than or equal to O. 


The output array size is smaller than the length of the data it is sis to 
contain. 


At least one array length is invalid or the offset + length is greater than the size 
of the array. 


The requested number was not found. 

The requested name was not found. 

The requested number was not found. 

The type code specified is out of the acceptable range. 
The flag specified is out of the acceptable range. 


The space for OSVs or total storage allocated in OUTPUT is not big enough for 
OSVs and/or PSVs. 


An invalid control character was detected in the template. 


DATE component specifies a value out of range. 


TIME component specifies a value out of range. 


continued 
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Table 16-2. Specific Descriptions for Internationalization Error Values (cont.) 


Error Value Specific Description 


An attempt was made to add a new convention with the name of an existing 
convention. 


3015 - The maximum digits value is either missing or out of range. 
| The fractional digits value is either missing or out of range. 
The international fractional digits value is either missing or out of range. 


The long date template is either missing or contains invalid information. 


The short date template is either missing or it contains invalid information. 


The numeric date template is either missing or contains invalid information. 


The long time template is either missing or it contains invalid information. 


3022 The numeric time template is either missing or contains invalid information. 
3023 The monetary template is either missing or it contains invalid information. 
3024 The numeric template is either missing or it contains invalid information. 

3027 The lines per page value is either missing or it is out of range. 

3028 _ The characters per line value is either missing or it is out of range. 

3029 A required symbol in either the monetary or the numeric template is missing. 
3030 An invalid template length value was encountered. 

3031 | A mutually exclusive combination of control characters has been encountered in 


a monetary or numeric template. 


The mindigits field in a “t’* control character in a monetary or numeric template 
is out of range. 


A right bracket “]’” is required to terminate a “t” control character symbol 
definition list. 


3034 An expected colon “:” is missing from the “t” contro! character in a monetary or 
numeric template. 


The input value did not contain digits or an expected symbol was missing. 


3036 Specified convention does not exist and cannot be retrieved, modified, or 
deleted. 


A convention definition cannot be added, modified, or deleted. 
The “PRECISION” parameter value is out of range. 
A required convention name was not provided. 


The named convention is a standard convention and cannot be modified or 
deleted. 


_ continued 
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Table 16-2. Specific Descriptions for Internationalization Error Values (cont.) 


Error Value Specific Description 


A hexadecimal value representing a symbol in a monetary or numeric template 
is missing a required delimiter. 


An invalid character was encountered in a hex value representing a symbol in a 
monetary or numeric template. 


The international currency notation is missing a required terminating delimiter. 


The requested data was not found. 
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Control of the Compilation Process 


The COBOL74 compiler enables you to control portions of the compilation process. 
You can control the way you start the compilation, the files you use as input to and 
the files produced as output from the compiler, and the various options that direct the 
compilation. 


Starting a Compilation 


Programs can be compiled through CANDE or WFL. You can choose the method that is 
the most familiar or the most convenient. 


You can make a COBOL74 file in CANDE by using the following CANDE syntax: 
MAKE <MYFILE> C74 | 


If a program is created of type C74, then you can enter the COMPILE command to begin 
the compilation. 


The default value of a compiler option can depend on whether the compilation starts 
from CANDE or WFL. If this is the case for a particular option, the default for both 
_CANDE and WFL compiles is documented under the description of the option. 


See Also 


e Refer to the CANDE Operations Reference Manual for information about the MAKE 
and COMPILE commands. These commands can be used to make and poner a file 
through CANDE. 


e WFL is invoked by using the WFL START command in CANDE. Refer to the WFL 
Reference Manual for information about compiling a program using a WFL deck. 


Using Cross-Reference Files 


- Across-reference file is a file that contains an alphabetized list of user-defined words 
that appear in a program. 
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For each user-defined word, the cross-reference information contains the following data 
as well as other information: 

e The type of the item the word identifies 

e The sequence number of the source input record at which the identifier is declared 
e The sequence number of the source input record at which the word is declared 

e The sequence numbers of the input records at which the word is accessed 
Depending on the values of five related compiler control options —N OXREFLIST, 


XDECS, XREF XREFFILES, and XREFS—the compiler optionally generates 
cross-reference information. 


The following Sree factors can be controlled through the use of sciames 
control options: 


e Whether the compiler saves cross-reference information as it processes the source 
input 


e Which user-defined words and which references to these words are cross-referenced 
e Whether the compiler starts the SYSTEM/KREFANALYZER utility automatically 


e Ifthe compiler starts the SYSTEM/KREFANALYZER utility automatically, 
whether the utility produces printed output, disk files suitable for input to the 
SYSTEM/INTERACTIVEXREF utility and the Editor, or both the printed output 
and the disk files 


The compiler saves cross-reference information if the XREF option, the XREFFILES 
option, or both options are TRUE. If used, these options should be assigned the value 
TRUE before the end of the IDENTIFICATION DIVISION. 


Table 17-1 shows the effects of setting the XREFS option, the XDECS option, or both 
compiler control options. The XDECS option must be used with the XREF option, the 
XREFFILES option, or both options. The XREFS option must be used with the XDECS 
option, and the XREF and XREFFILES options. 


Table 17-1. Effects of the XDECS and XREFS Compiler Control Options 


Options That Are Set Effects 


Any of the following combinations: Selects the user-defined words to be 
e  XREF and XDECS cross-referenced. 


@ XREFFILES and XDECS 
--@  XREF, XREFFILES, and XDECS 
XDECS No effect when set by itself. 


continued 
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Table 17-1. Effects of the XDECS and XREFS Compiler Control Options (cont.) 


Options That Are Set Effects 


Any of the following combinations: Selects the user-defined words to be 


cross-referenced. If XDECS is FALSE, the 
e —XREF and XREFS XREFS option has no effect. 


e XREFFILES and XREFS 
e REF, XREFFILES, and XREFS 
XREFS 


No effect when set by itself. 


When the compiler is saving cross-reference information, this information is written 
to a disk file in raw form. Before this information can be printed or read by the 
SYSTEM/INTERACTIVEXREF utility or the Editor, it must be analyzed by the 
SYSTEM/XREFANALYZER utility. 


You have the eetian of instructing the compiler not to start the SYS- 
TEM/XREFANALYZER utility, keeping the raw file of the compiler on disk. Table 17-2 
show the effects of setting the NOXREFLIST option. 


Table 17-2. Effects of the NOXREFLIST Option 


NOXREFLIST Option Value Effect 


The compiler automatically starts the 
SYSTEM/XREFANALYZER utility to process the raw 
cross-reference file. 


The compiler does not start the SYSTEM/XREFANALYZER 
utility, and the raw file of the compiler is left on disk with the 
title XREF/code-file-name, where code-file-name is the name 
of the object code file produced by the compiler. You can 
then run the SYSTEM/KREFANALYZER utility directly at a 
later time to analyze the raw file. 


If the compiler starts the SYSTEM/XREFANALYZER utility (that is, if the 
NOXREFLIST option is FALSE), the program produces either a printed listing or a pair 
of disk files suitable for the Editor and the SYSTEM/INTERACTIVEXREF utility. 
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Table 17-3 shows the effects of the XREF and XREFFILES options when the 
NOXREFLIST option is FALSE. 


Table 17-3. Effects of the XREF and XREFFILES Options 


Options That Are Set _ 
XREF Produces a listing. 


XREFFILES Produces two disk files. These file are titled 
XREFFILES/code-file-name/XREFS and 
XREFFILES/code-file-name/XDECS. 


XREF and XREFFILES Produces both a listing and the disk files. 


References and declarations in the interactive cross-reference files and variables within 
a copy library refer to the line number of the COPY statement in the source program. 
These references and declaratives do not refer to the actual line numbers within the 
copy library. However, when both the XREF and XREFFILES options are set, the actual 
line numbers within the COPY file are used for the references and the declarations. 


Note: If syntax errors occur, the cross-reference information is 
still produced but might be unreliable. In extreme cases, the 
SYSTEM/XREFANALYZER utility might then fail. 


See Also 


e Refer to “NOXREFLIST,” “XDEC,” “XREB” “XREFFILES,” and “XREFS” later in 
this section for more information about these options. 


e Refer to the discussion of the SYSTEM/XREFANALYZER and 
SYSTEM/INTERACTIVEXREF utilities in the A Series System Software Utilities 
Manual for more information about cross-reference files. 


e Refer to the Editor Operations Guide for information about getting cross-reference 
information while in the Editor. 


Performing a Separate Compilation 


17-4 


You can separately recompile selected areas of a previously compiled COBOL program by 
using the SEPCOMP compiler control option. To perform a separate compilation, you 
must first compile the program with the compiler control option MAKEHOST assigned 
the value TRUE. This step creates the host file. The host file is an executable code file 
that contains additional information necessary for a separate compilation. Given only 
the name of the host file, the name of the original source, and the patches to change 

the source, the compiler is able to separately compile the patched areas, resulting in an 
abbreviated compilation. Only the affected areas of the program are actually compiled. 


You can use the separate compilation facility as a supplement to, not a replacement for, 
the standard method of compilation. This separate compilation is meant to be used in 
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development work on large COBOL programs where a reduction in the time required for 
compilation of large programs can be beneficial. 


The following considerations for using the SEPCOMP option apply when you are 
performing a separate compilation procedure: 


e The SEPCOMP option cannot be explicitly referenced after the beginning of the 
compilation. 


e The SEPCOMP option cannot be set more than once because when the option is first 
set, the SEPCOMP option starts the preprocessing of the CARD file input. 


e The title of the host program can be specified either as a string within parentheses 
immediately following the word SEPCOMP on the CCR, or by a file equation to the 
host file in the COBOL compiler. The optional string specification has precedence 
over the file equation. The host file contains the name of the symbolic file from 
which it was compiled. | 


Examples 


Example 17-1 shows a separate compilation using a WFL deck in which the title of the 
host program is given as a string. 


?BEGIN JOB COMPILE/A/B; 
- COMPILE A/B WITH COBOL74 LIBRARY; 
COBOL DATA | 
@@0G18$ SEPCOMP ("A/HOST") LIST MAP 


<patch records> 


?END JOB 
Example 17~1. Separate Compilation with the Host Title Given as a String 


Example 17-2 shows a separate compilation using a WF L deck in which the title of the 
host program is file-equated to the COBOL file host. 


?BEGIN JOB COMPILE/A/B; 
COMPILE A/B WITH COBOL74 LIBRARY; 
COBOL FILE HOST (FILENAME=A/HOST) ; 
COBOL DATA 

@20019$ SEPCOMP LIST MAP 


<patch records> 


?END JOB . 
Example 17-2. Separate Compilation with the Host Title File-Equated 
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Providing the Changed Records 


A patch record is a record with a nonblank sequence number; that is, at least one digit of 
the sequence number is required. Once the host file name is known, the patch records 
must be provided. The compiler examines the patch records of aSEPCOMP compilation 
to determine the sections or code segments that need to be recompiled. The output from 
a SEPCOMP compilation is an executable code file that, unlike ALGOL and NEWP files, 
cannot be used as the host file for the next SEPCOMP compilation. 


The compiler accepts compiler control records (CCRs) with blank sequence numbers. 
following the compiler control record that sets the SEPCOMP option ene before the first 
patch record. 


Sequence errors are not allowed among patch records having nonblank sequence 
numbers. 


Observing Compilation Restrictions 
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‘You are responsible for observing the folewing restrictions when performing a separate 


compilation: 


e The host symbolic file and all of the COPY library files must be unchanged since the 
MAKEHOST compilation. A SEPCOMP compilation verifies this requirement by. 
checking the date and timestamp. 


e Both the host symbolic file and the patch file for a SEPCOMP seinen must be in 
sequential order. 


e You must use a COBOL compiler of the same release level for both the MAKEHOST 
and SEPCOMP compilations. 


e The SEPCOMP option is not available for compilations of programs that access 
DMSII databases. 


e The SOURCE (host symbolic) file must be assigned to a mass-storage device, 
because random access is necessary. 


e All new label declarations must be unique, regardless of qualification. 


e Only PROCEDURE DIVISION statements are allowed to be patched with the 
SEPCOMP compilation facility. 


e New PROCEDURE DIVISION statements can be added, and existing statements 
can be modified or deleted. PROCEDURE DIVISION labels can be deleted as long 
as the label is referenced only within the code segment in which the label resides. 


e The SORT, MERGE, USE, and ALTER verbs cannot be used in either the 


MAKEHOST or the SEPCOMP compilation. 
e ADECLARATIVES SECTION cannot be added, deleted, or modified. | 
e The DEBUG facility of COBOL cannot be used with a SEPCOMP compilation. 


If any of the preceding restrictions are violated, the COBOL compiler aborts the _ 
SEPCOMP compilation. 
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The sean es control options MERGE, NEW, OPTIMIZE, and STATISTICS are ignored 
during a MAKEHOST or a SEPCOMP compilation. 


The compiler control options MERGE and XREF are ened during a SEPCOMP 
compilation. 


See Also 
e For information about creating a host file, refer to “MAKEHOST” later in this 
section. 


e For information about separately recompiling selected areas of a previously compiled 
program, refer to “SEPCOMP” later in this section. 


Compiler Control Option Concepts 


Compiler control options provide control of the following compiler functions: 


e Source language input 
e Source language output 
-e Optional compilation mechanisms 
e Printed output 
e Compiler diagnostic messages 
e Compiler debugging 
e User options 
e Code generation 
You can specify these options on compiler control records (CCRs). A CCR contains 


compiler control statements made up of options or groups of options and the associated 
parameters, if any. By using CCRs, you can control the options provided by the compiler. 


Types of Compiler Control Records (CCRs) 


A CCR can be either temporary or permanent. The differences between the two types of 
CCRs are described in the following list: 


e Temporary CCRs apply only to a given compilation. These CCRs have a dollar 
currency sign ($) in column 7. 


e Permanent CCRs remain associated with the source language. These CCRs have a 
dollar currency sign ($) in columns 7 and 8. The compiler includes permanent CCRs 
in any NEWSOURCE file created. 
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Types of Compiler Control Options 
| A compiler control option can be of type Boolean, value, or immediate. The following lists 
show the options belonging to each category. 
Boolean 
A Boolean option is either enabled (set to TRUE) or disabled (set to FALSE). When 
enabled, the option directs the compiler to apply 2 an associated function to all subsequent 


processing until the option is disabled. 


Boolean options can also have associated parameters related to the function affected by 
the Boolean option. The Boolean options are as follows: 


BINARYCOMP GROUPMOVEWARN = MERGE SPEC 
BINDINFO INFO NEW STATISTICS 
CODE LIBS NEWID SUMMARY 
COMPILERDEBUG LIBDOLLAR NOXREFLIST TADS 
DATADICTINFO LIBRARYLOCK OMIT TEMPORARY 
DELETE LINEINFO OPT | User Option 
DICTIONARY LIST OPTIMIZE WARNFATAL 
DOUBLE LISTDELETED OWN WARNSUPR 
ERRORLIST LIST$ OWNTEMP XDECS 
FREE LISTDOLLAR SEPCOMP XREF 
GLOBAL LISTOMITTED SEQ XREFFILES 
GLOBALTEMP LISTP SEQCHECK XREFS 

LIST1 | SEQUENCE 


Value 


A value option directs the compiler to store.a value associated with a given function. The 
value options are as follows: 


DEBUG Sequence Increment 
ERRORLIMIT | SHARING 
FEDLEVEL . Symbolic ID 

LEVEL - TARGET 


Sequence Base 
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Immediate 


An immediate option directs the compiler to apply a function that is independent of 
subsequent processing. Immediate options can also have associated parameters. The 
immediate options are as follows: 


CLEAR 
PAGE 
VOID 


Compiler Control Option Formats 


The following text describes how compiler control options are formatted. 


compiler control record 


The following is the general format for a compiler control record (CCR): 


SET Boolean-option 
POP immediate-option }... 


RESET 
SET {Boolean-option [ = option-expression |}... 


value-option 


option-expression 


The following is the general format for an option expression: 


AND Boolean-option-2 
[ NOT] { ( ea ane 7 


Explanation of Formats 

CCRs must have a dollar currency sign ($) in column 7 and can have an optional dollar 
sign in column 8. The options follow the dollar currency sign, and one or more spaces 
follow each option. No option can continue past column 72 of a CCR. 


The option expressions follow the standard rules of Boolean algebra for statement 
. evaluation. 
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CCRs can be interspersed at any point in the source language input. However, a CCR 
might affect the syntactical element that precedes it for the following reason. The CCR 
that follows a COBOL74 syntactical element actually is processed while the compiler 

is preparing that syntactical element for future analysis and delivering the previous 
syntactical element for parsing. 


Special attention should be paid to the use of CCRs in the immediate vicinity of 
COPY statements. For example, ifa COPY statement immediately follows a CCR, 
the options specified in the CCR can affect the first record included as a result of the 
COPY statement, unless these options are explicitly prevented from doing so. Adding 
a semicolon (;) after the ending period in the COPY statement ensures that the option 
changes take effect after all source information from the COPY statement has been 
processed. 


Because the CCR can affect the preceding statement or clause, Unisys recommends that 
a dummy statement be inserted between the two records to avoid unexpected results. 


Some options affect generated object code. These effects are discussed in the description 
of the particular option. 


See Also 


e For information about instructing the compiler to treat all COMPUTATIONAL 
items as if they were declared USAGE IS BINARY, refer to “BINARYCOMP” in this 
section. 


e For information on causing all data items in the WORKING-STORAGE SECTION to 
_ be global except those specifically declared LOCAL or OWN, refer to “GLOBAL” in 
this section. 


e For information on causing all data items in the WORKING-STORAGE SECTION to 
be OWN except those specifically declared LOCAL or GLOBAL, refer to “OWN” in 
this section. 


e For information about the COPY statement, refer to “COPY” in Section 9, 
“PROCEDURE DIVISION Statements.” 


Option Action Indicators 


Option action indicators preceding a list of options set, reset, or recall the last setting of 
each settable option in the list. 


A register that reflects the last 47 settings of the option is associated with each of the 


settable options. The presence of any preceding epion action indicator is ignored when 
nonsettable options are processed. 
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The option action indicators are defined as follows: 
Indicator Meaning 


SET The current setting of each option specified is saved, and each of the options is 
set to TRUE (enabled or on). The option can also be set to the value of an 
optional Boolean expression. 


RESET The current setting of each option specified is saved, and each of the options is 
set to FALSE (disabled or off). 
POP The current setting of each option specified is discarded, and each of the 


options is set to its prior setting. When no prior setting exists, a POP option 
action indicator leaves the option set to FALSE. 


A CCR that consists solely of a dollar currency sign ($) and no option information has no 
effect unless the MERGE option is TRUE. If the MERGE option is TRUE and a record is 
present in the secondary input file (SOURCE file) that has the same sequence number 
as the blank CCR, then the source record is ignored. 


A CCR that contains valid information in the primary input file (CARD file) always takes 


effect before a CCR that already exists in the secondary input file (SOURCE file) if the 
MERGE option is set and both records have the same sequence number. 
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COBOL74 Source and Object Files 


Source input is submitted to the COBOL compiler as one or more punched card, disk, 
or magnetic tape files. If more than one source file is used, the input from these files is 
merged on the basis of sequence numbers or as specified by the COPY statement. In 
addition to the object code file, the COBOL compiler produces the following optional 
output files: an updated symbolic file, an error message file, and a printer listing 
containing the source records and compiler control records (CCRs) used by the compiler, 
and other types of information. 


Figure 17-1 shows the flow of input and output data during compilation. 


Compi ler-generated 
output files 


Compiler input files 
(source language 
input and compiler 
control statements) 


Updated 
symbol 
(NEWSOURCE) 


Primary 
input 
(CARD) 


Program 
execution 


Secondary Line printer 


listing 
(LINE) 


input Compiler 
(SOURCE) 


= 
=: ee 
Source 
input by . 
COPY library ro o- pet eae 
ae ee | (ERRORFILE 
or ERRORS) 
| 
| 
| 
L. Cross-reference 
_ information 


(XREFFILE) 


Figure 17-1. Compiler Data Flow 
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Input Files 


The compiler accepts input from the CARD file, the SOURCE file, and the COPY library 
files. Input can be from the CARD file only, from the CARD file and the SOURCE file, 
from the CARD file and the COPY library files, or from all three. 


Table 17—4 shows the file attribute name, its assigned value, and its purpose for the 
compiler input files. 


Table 17-4. Attribute Values for the Compiler Input File 


Purpose 


EXTMODE EBCDIC or ASCIl Specifies the character type of the 
physical file. 


DEPENDENTSPECS TRUE Specifies that the format of the records 
and the structure of the logical file should 
be determined by the structure of the 
associated permanent file. : 


INTMODE . EBCDIC Specifies the units for the BLOCKSIZE and 


MAXRECSIZE attributes. 


MAXRECSIZE Taken fromthe Defines the smallest unit of the file that 
length of the the program can read from or write to at 
physical file. any one time. 


BLOCKSIZE Taken from the Defines the smallest unit of the file that 
length of the * the I/O subsystem can physically read 
physical file. from or write to. Because the value of the 

BLOCKSIZE attribute for this file is 
assumed from the physical file, this 
attribute does not require explicit 
assignment. 


Each file has an internal name specified by the INTNAME file attribute. Each file is 
assigned to a device specified by the KIND file attribute. Table 17-5 shows the internal 
name and the device to which the file is assigned for each compiler input file. In some 
cases, the default device depends on whether the compilation is started from CANDE or 
WFL. 
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Table 17-5. Compiler Input Files 


Internal Language | 
Name Initiation Device Explanation 


READER The CARD file supplies the primary 
source input to the compiler and must 
be present for each compilation. If the 
compilation is started from CANDE or 
WEL, and the compiler file equation is 
not applied to the CARD file, the file is 
assumed to be a card reader file. 


If the compilation is started from 
CANDE and compiler file equation is 
not applied to the CARD file, the file is 
assumed to be a disk file. 


SOURCE SOURCE The SOURCE file, which is optional, 
supplies secondary source input to the | 
compiler. If the compiler file equation 
is not applied to the SOURCE file, the 
file is assumed to be a disk file 
regardless of whether the compilation 
is started from WFL or CANDE. 


When this file is present and the 
MERGE option is TRUE, records from 
the SOURCE file are merged with those 
of the CARD file on the basis of 
sequence numbers. If a record from 
the CARD file and a record from the 
SOURCE file have the same sequence 
number, the CARD file record is 
compiled and the SOURCE file record 
is ignored. 


COPY files COPY library files provide source input 
to the compiler in addition to that 
supplied by the CARD and SOURCE 
files and are present only if one or 
more COPY statements appear in the 
CARD or SOURCE files. 


See Also 


e For information about merging source-language records from the CARD and 
SOURCE files, refer to “MERGE” later in this section. 


e For information on the COPY statement, refer to “COPY” in Section 9, 
“PROCEDURE DIVISION Statements.” 
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e Refer to the I/O Subsystem Programming Guide for information about using file 
attributes. 


e Refer to the WF'L Reference Manual for detailed information pertaining to the 
compiler file equation. 


Output Files 


The compiler produces one to five output files. These files are the CODE file, the 
NEWSOUKCE file, the LINE file, the ERRORFILE file, and the XREFFILE file. 
Table 17-6 explains-each of these files. 


Table 17-6. Compiler Output Files 


File Explanation 


CODE file The CODE file is produced unconditionally and contains the executable 
object code produced by the compiler. Whether this file is discarded 
after compilation, executed and then discarded, or stored permanently 
depends on the specifications in the COMPILE statement and whether or 

not syntax errors occurred during compilation. 


NEWSOURCE file The NEWSOURCE file is produced only if the NEW option is TRUE. The 
NEWSOURCE file is an updated source file that contains the portion of 
source input from the CARD and SOURCE files that was actually 
compiled. If the compiler file equation is not applied to the 
NEWSOURCE file, the file is written to disk. 


LINE file The LINE file is produced unless the LIST option is FALSE. If the 
compiler is started from CANDE, the default value of the LIST option is 
FALSE and must be explicitly set to TRUE for the LINE file to be 
produced. If the compiler is started from WFL, the LINE file is produced 
by default. If the compiler file equation is not applied to the LINE file, 
the file is written to the printer. 


The contents of the LINE file depends on the values of the CODE option 
and the MAP option; however, when printed, the line file contains the _ 
following minimum information: 


e Source used as input to the compiler 
e Code segmentation information 


e Error messages and error count, if syntax errors occur 


continued 
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Table 17-6. Compiler Output Files (cont.) 


File Explanation 


ERRORFILE file The ERRORFILE file is produced only if the ERRORLIST option is TRUE. 

If the compiler is started from WFL, the default value of the ERRORLIST 
_ option is FALSE and must be explicitly set to TRUE for the ERRORFILE 

file to be produced. If the compiler file equation is not applied to the 
ERRORFILE file, the file is written to the printer. If the compiler is started 
from CANDE, the ERRORFILE file is produced by default and written to 
the remote station that started the compiler. If no syntax errors occur 

during compilation, no ERRORFILE file is produced regardless of the 

value of the ERRORLIST option. 


For every record that contains syntax errors, a copy of the source record 
containing the error is written to the ERRORFILE file, followed by the 
syntax errors that occurred for that record. 


The synonym ERRORS can be used instead of ERRORFILE. If you 
do not file equate to either ERRORFILE or ERRORS, the file is created 
with the title ERRORS. If you file equate to both ERRORFILE and 
ERRORS, only the equation to ERRORS is used. 


XREFFILE file When either the XREF or XREFFILES compiler control option is TRUE, 
the compiler saves raw cross-reference information in the XREFFILE file. 
The XREFFILE file is named XREFFILES/code-file-name, where 
code-file-name is the name of the object code file produced by the 
compiler. The SYSTEM/XREFANALYZER utility can read this file to 
produce a printed cross-reference file, a disk XREFFILE file, or both for 
use with the SYSTEM/INTERACTIVEXREF utility or the Editor utility. The 
SYSTEM/XREFANALYZER utility is run automatically unless the 

NOXREFLIST compiler control option is TRUE. 
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Table 17-7 summarizes the attribute settings for each type of compiler output file. For 
the file ERRORFILE, the default device depend on whether the compilation starts from 
CANDE or from WFL. 


Table 17-7. Attribute Assignments for Compiler Output Files 


INTNAME _ KIND INTMODE MAXRECSIZE BLOCKSIZE 
CODE Disk HEX | 30 words 150 words 
NEWSOURCE Disk © EBCDIC 15 words 450 words 
LINE Printer EBCDIC 22 words 22 words 


ERRORFILE Printer EBCDIC 12 words 12 words 
(WFL) . 


ERRORFILE Remote EBCDIC 12 words 12 words 
(CANDE) 


XREFFILE Disk EBCDIC 510 words 510 words 


Legend 
ERRORFILE Synonymous with ERRORS 


See Also 
e Refer to the discussions of the COMPILE statement in the WFL Reference Manual 
and the CANDE Operations Reference Manual. 


e For information on creating a new re ee symbolic, refer to “NEW” in this 
section. 


e For information on Ea emane a listing of the object ici refer to “CODE?” in this 
section. 


e For information on requesting a map of variables in the object program, refer to 
“MAP” later in this section. . 


e For information about cross-reference files, refer to “Using Cross-Reference Files” 
earlier in this section. 


Compiler Control Options 


The following paragraphs describe the general format, the default settings, and the 
details of the individual compiler control options. The options are listed in alphabetic 
order. : 
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BINARYCOMP 


BINARYCOMP 


(Type: Boolean, Default: FALSE) 


The BINARYCOMP option directs the compiler to treat all COMPUTATIONAL items as 
if they were declared USAGE IS BINARY. 


The compiler examines the current setting of the BINARYCOMP option as it parses 
each data declaration, after it examines the level-number, and before it examines the 
data-name. A change to the BINARYCOMP option within a data declaration affects the 
data item if the option change occurs before the first clause following the data-name. 


Unisys recommends not changing the BINARYCOMP option within the clauses of a data 
declaration. Instead, the option should be changed either before the level number or 
after the ending period of the data declaration. 


BINDINFO 


(Type: Boolean, Default: FALSE) 


- The BINDINFO option causes information used for binding to be placed in the code 
file unconditionally. This information is then available to the PROGRAMDUMP and 
DUMPANALYZER utilities. 


The BINDINFO option has no effect on programs compiled with the LEVEL option set 
to 3 or higher, nor does the BINDINFO option affect programs that call an external 
procedure. Binding information is always produced for such programs. 


The setting of this option cannot be changed after the first source record. 
The BINDINFO option is incompatible with the STATISTICS and TADS options. If an 
attempt is made to set both the STATISTICS and BINDINFO options to TRUE, the 


first option that became TRUE is unaffected, the second option is set to FALSE, and a 
warning message is issued. 
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CLEAR 


CLEAR 


(Type: Immediate) 


The CLEAR option sets to FALSE the current setting and all previous settings of all 
Boolean options except MERGE, OPTIMIZE, and, conditionally, NEW, STATISTICS, 
FREE, and LINEINFO. 


If a source-language record has been written to the new symbolic file (NEWSOURCE) as 
a result of the NEW option, then the NEW option is not set to FALSE. 


If the first source record has been processed, STATISTICS, FREE, and LINEINFO are | 
not set to FALSE. 


CODE 


(Type: Boolean, Default: FALSE) 


The CODE option provides a listing of the object code. 


COMPILERDEBUG 


This option is for Unisys internal use only. 


DEBUG 


This option is for Unisys internal use only. 
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DELETE 


DELETE 


(Type: Boolean, Default: FALSE) 


The DELETE option discards source-language records from the secondary input 
(SOURCE file) until the option becomes FALSE. 


This option can appear only on a CCR in the primary source-language input (CARD file). 


If the MERGE option is FALSE, the compiler ignores the DELETE option. The 
DELETE option does not alter the normal merging process. The compiler does not 
carry forward the discarded source-language records to the output symbolic file 
(NEWSOURCE file) if the NEW option is TRUH, and these records are not listed unless 
the LISTDELETED option is TRUE. 


See Also 


For information on listing discarded source-language records, refer to “LISTDELETED” 
later in this section. 


DOUBLE 


| (Type: Boolean, Default: FALSE) 


The DOUBLE option double-spaces all printed output. 
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ERRORLIMIT 


ERRORLIMIT = integer 


(Type: Value, Default: 10 for compilations originated through CANDE; otherwise, 150) 


The ERRORLIMIT option specifies the maximum number of errors that the compiler 
can produce before a compilation is ended. 


If the error limit is exceeded, the compiler produces a listing of the errors and informs 
you that the compilation was ended because the error limit was exceeded. 


If the error limit is exceeded and the NEW option is TRUE, then the new symbolic file 
(NEWSOURCE) is purged. 


ERRORLIST 


ERRORLIST 


(Type: Boolean, Default: TRUE for compilations originated through CANDE; otherwise, | 
FALSE) 


The ERRORLIST option causes syntax errors to be written to the file ERRORFILE. 


When the compiler detects a syntax error in the source input, it writes the line of text in 
error, an error message, and a pointer to the syntactical item in question on two lines in 
the file ERRORFILE. The ERRORLIST option is provided primarily for use when the 
compiler is called from a remote terminal through CANDE, but the option can be used 
regardless of the manner in which the compiler is called. 


When the compiler is called from CANDE, the default value of the ERRORLIST option _ 


_ is TRUE and the file ERRORFILE is automatically equated to the remote device from 
which the compilation originated. 
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FEDLEVEL 


FEDLEVEL | = 


(Type: Value, Default: 4) 


The FEDLEVEL option provides a facility for specifying and evaluating levels of COBOL 
to measure compliance with U.S. Government COBOL standards. 


The default value for FEDLEVEL with no level is 4. 


The compiler produces nonfatal warnings for constructs not available at the level at 
which the program was compiled. For example, if FEDLEVEL is set to 2, all constructs 
allowed only for level 3 and higher produce warnings. 


The 01-level corresponds to the U.S. Government low-level, the 02-level corresponds 
to low-intermediate, the 03-level corresponds to high-intermediate, and the 04-level 
corresponds to high-level. The 05-level includes all Unisys A Series extensions to the 
ANSI standard. 


If the FEDLEVEL option is set to 5 and there is a program-name specified in the 
PROGRAM.-ID clause, that name is used as the entry-point-name. Otherwise, the 
entry-point-name is PROCEDUREDIVISION. 


FREE 


(Type: Boolean, Default: TRUE for ene originated ere CANDE; otherwise, | 
FALSE) 


The FREE option removes most of the margin restrictions required by COBOL. This 
option must be FALSE when you are using a debugging line in the program. Because 
the default setting is TRUE for compilations started from CANDE, you must remember 
to explicitly set the option to FALSE. 
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See Also 


For a description of debugging lines, refer to “Debugging Lines” in Section 11, 
“Debugging.” 


GLOBAL 


(Type: Boolean, Default: FALSE) 


The GLOBAL option causes all data items in the WORKING-STORAGE SECTION and ° 
the FILE SECTION to be global except those specifically declared LOCAL or OWN. 

The GLOBAL option only affects the data descriptions in the FILE SECTION, not the 
files themselves. The GLOBAL option has no effect on entries in the ENVIRONMENT 
DIVISION or the COMMUNICATION SECTION. 


If the compilation is an 02-level, the GLOBAL option is ignored. The OWN and 
GLOBAL options cannot both be TRUE. 


As the compiler parses each data declaration, it checks the setting of the GLOBAL 
option when the current syntactical element is the data-name in the declaration and the 
next syntactical element has been prepared for future analysis. If an ending period 
follows the data-name and the next syntactical element is a CCR that changes the setting 
of the GLOBAL option, the new GLOBAL option setting affects the data item. 


To prevent the new GLOBAL option setting from affecting the data item, redundant 

clauses or semicolons (;) can be inserted in the data declaration that precedes the CCR so 
that at least one syntactical element exists between the data-name and the ending period — 
of the data declaration. 


Unisys recommends not changing the GLOBAL option within the clauses of a data 
declaration. Instead, the option should be changed either before the level number or 
after the ending period of the data declaration. 


The VALUE clause cannot be used with the GLOBAL option. 


8600 0296-000 7 | 17-23 


Control of the Compilation Process 


GLOBALTEMP 


GLOBALTEMP 


(Type: Boolean, Default: FALSE) 


The GLOBALTEMP option causes the temporary arrays generated by the compiler for 
the processing of some statements to be global. The GLOBALTEMP and OWNTEMP 
compiler control options cannot both be TRUE. If the GLOBALTEMP option is TRUE in 
a program compiled at the 02-level , then the temporary arrays for the host program are 
also shared by all bound procedures in which the GLOBALTEMP option is TRUE. 


This option must appear before the first source record and cannot appear on any 
compiler control record (CCR) after the first source record. 


Note This option can produce unpredictable errors or results if used in a 
bound procedure that is then used as an asynchronous process (that 
is, by an ALGOL PROCESS statement). 


GROUPMOVEWARN 


GROUPMOVEWARN 
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(Type: Boolean, Default: FALSE) 


The GROUPMOVEWARN option issues a warning whenever the compiler encounters 
a MOVE statement in which one operand is a group item, the other operand is 

an elementary item, and the usages of the two operands differ. Some compilers 

and systems generate incorrect results for MOVE statements of this type. The 
GROUPMOVEWARN option is useful for programs migrating from such systems 
because it identifies code that is expecting results contrary to the requirements of the 
standard. 


If the ERRORLIST option is TRUE, the compiler produces an ERRORFILE file. The 
ERRORFILE file contains the warnings produced by the GROUPMOVEWARN option 
even if there were no actual syntax errors in the program. 


The warning messages produced by the GROUPMOVEWARN opean: are not suppressed 
by the WARNSUPR option. 


The GROUPMOVEWARN option must appear before the first source record and cannot 
appear on any compiler control record (CCR) after the first source record. 


8600 0296-000 


Control of the Compilation Process 


Example 


Example 17-3 illustrates the situation that the. GROUPMOVEWARN option is intended 
to help diagnose. 


* The record description 
* 
1 THE-RECORD. 
@3 A-PACKED-DATE PIC 9(6) COMP VALUE 931998. 
@3 A-GROUP-ITEM. 
@5 DATE-YEAR PIC 99. 
@5 DATE-MONTH PIC 99. 
@5 DATE-DAY' PIC 99. 
@3 AN-ELEMENTARY-ITEMS REDEFINES A-GROUP-ITEM PIC 9(6). 


PROCEDURE DIVISION 


After execution of the next statement, the correct value for 
THE-RECORD is @831998031998404949@. Since a move operation 
involving group items is an alphanumeric-to-alphanumeric move, 
the move operation transfers 3 bytes of data from A-PACKED-DATE 
to the first 3 bytes of A-GROUP-ITEM, and nulls the remainder of 
of A-GROUP-ITEM with spaces. 


+ + + + F FF F F 


MOVE A-PACKED-DATE TO A-GROUP-ITEM. 


After execution of the next statement, the correct value for 
THE-RECORD is @831990FOF3F1FOF9FOG. This is an elementary numeric 
move operation, and as such, the data is transformed from 
computational to display form in the process. 


+ + + + # 


MOVE A-PACKED-DATE TO AN-ELEMENTARY-ITEM. 


e 
° 


Example 17-3. Understanding the GROUPMOVEWARN Option 


INFO 


(Type: Boolean, Default: FALSE) 


This option is for Unisys internal use only. 
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LEVEL 


LEVEL = integer 


(Type: Value, Default: 2) 
The LEVEL option controls the lexicographical level at which the compilation is to occur. 


The integer must be in the range from 2 through 14. The LEVEL option must appear 
before the IDENTIFICATION DIVISION. 


LIB$ OR LIBDOLLAR 


LIB$ 
LIBDOLLAR 


(Type: Boolean, Default: FALSE) 


The LIB$ option causes a CCR that occurs as part of a COBOL library file to be 
processed.. When this option is FALSE, CCRs in a COBOL library file are ignored. 


_ This option is treated as an error if it occurs on a CCR in a COBOL library file. 


LIB$ and LIBDOLLAR are synonymous. 


LIBRARYLOCK 


LIBRARYLOCK 


(Type: Boolean, Default: FALSE) 


When TRUE, the LIBRARYLOCK option provides ceing code to maintain data 
integrity for private libraries. 


See Also 


e For information on specifying the way a program is shared when it is called as a 
library, refer to “SHARING” later in this section. 


e Fora description of the compiler control options that determine the way a library is 
used, refer to “Library Compiler Control Options” in Section 15, “Libraries.” 
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LINEINFO 


LINEINFO 


(Type: Boolean, Default: TRUE for compilations originated through CANDE; otherwise, 
FALSE) . . 


The LINEINFO option saves source-language sequence numbers in the code file so that 
if the object program abnormally ends, you can investigate the problem by program 
sequence number rather than by code address. 


LIST 


(Type: Boolean, Default: FALSE for compilations originated through CANDE; 
otherwise, TRUE) 


. The LIST option produces 


e Asource-language listing 
e Acompilation summary 


e Anerror message listing 


LIST$ or LISTDOLLAR 


LIST$ 
LISTDOLLAR 


(Type: Boolean, Default: FALSE) 
The LIST$ option lists all temporary CCRs encountered during the compilation. 


LIST$ and LISTDOLLAR are synonymous. 
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LISTDELETED 


LISTDELETED 


(Type: Boolean, Default: FALSE) 


The LISTDELETED option lists that part of the source-language input that was deleted 
by the DELETE or the VOID option. 


LISTOMITTED 


LISTOMITTED 


(Type: Boolean, Default: FALSE) 


The LISTOMITTED option lists that part of the source-language input that was omitted 
by the OMIT option. 


LISTP 


(Type: Boolean, Default: FALSE) 


‘The LISTP option lists source-language records that originate from the primary input 
file (CARD file). 


If the LIST option is TRUE, this option has no effect. 


LIST1 


LIST 1 


(Type: Boolean, Default: FALSE) 


The LIST1 option produces a listing during the first pass. 
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MAKEHOST 


(Type: Boolean, Default: FALSE) 


The MAKEHOST option creates a host file when compiling a COBOL program. The 
output host file is an executable code file that is then used as one of the inputs to a 
SEPCOMP compilation. 


The code segments of a MAKEHOST compilation are different from those of a normal 
compilation. All MAKEHOST sections are placed into separate code segments, as 

opposed to putting contiguous sections with the same sa -number in the same code 
segment, which is done in a normal ca a 


The MAKEHOST option must appear as the first record of the compiler input file. 
The MAKEHOST option is incompatible with the MERGE, NEW, OPTIMIZE, and 


STATISTICS options. If one of these options is used with the MAKEHOST option, then 
the option is ignored and a warning message is issued. 


The MAKEHOST option is also incompatible with programs invoking DMSII databases. 
If such an invocation is encountered during compilation, a warning message is issued and 
the MAKEHOST option is set to FALSE. 


(Type: Boolean, Default: FALSE) 


The MAP option includes information concerning the allocation of variables in the object 
program as part of the output listing. 
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MERGE 


MERGE (filet a } | | ) 


TAPE 


(Type: Boolean, Default: FALSE) 


The MERGE option starts the process that merges the primary source-language records 
(CARD file) with the secondary source- eanguage input records (SOURCE file) specified 
by the MERGE parameters. 


The file title must be a string. If you do not specify a file title, SOURCE is assumed, 
unless this file title is preempted by a file equation. 


If you do not specify a device, DISK is assumed, unless preempted by a file equation. 


This option remains TRUE throughout a compilation. If you try to change this option, 
your attempt is treated as an error and is ignored. 


You cannot use the MERGE option with the MAKEHOST and SEPCOMP options. If. 
the MAKEHOST option is TRUE or becomes TRUE, the compiler reads the SOURCE | 
file as the compiler input file, but the compiler issues a warning message and stops 
reading records from the CARD file. If the SEPCOMP option is TRUE or becomes 
TRUE, the MERGE option is set to FALSE and the compiler issues a warning message. 


NEW 


DISK 
NEW | ( file-title {Pack | 


TAPE 


(Type: Boolean, Default: FALSE) 


The NEW option creates a new source-language symbolic file (NEWSOURCKE file) of all 
source-language records accepted for compilation. 


The file title must be a string. Ifyou do not specify a file title, NEWSOURCE is assumed 
unless it is preempted by a file equation. 


Ify you do not specify a device, DISK is assumed unless it is preempted by a file equation. 


This option starts the writing of all input source-language records accepted for 
compilation to a new symbolic file (NEWSOURCE file). Source-language records 
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discarded by the DELETE or VOID options are excluded; however, input records 
omitted by the OMIT option and permanent CCRs are included. 


Once set to TRUE, this option remains TRUE throughout a compilation. An attempt to 
change this option is treated as an error and is ignored. 


You cannot use the NEW option with the MAKEHOST and SEPCOMP options. If the 
MAKEHOST or the SEPCOMP option is TRUE or becomes TRUE, the compiler sets 
the NEW option to FALSE and issues a warning message. 


NEWID 


(Type: Boolean, Default: FALSE) 


The NEWID option replaces the rightmost eight character positions of the 
source-language record with the symbolic-id literal aesocintes with this option. 


If this option i is FALSE, the rightmost eight character positions of the source-language 
record remain unchanged. 


See Also 


Refer to “Symbolic ID” later in this section for information on this literal. 


NOXREFLIST 


NOXREFLIST 


(Type: Boolean, Default: FALSE) 


When set to TRUE, the NOXREFLIST option prevents the SYSTEM/XREFANALYZER 
utility from being started by the compiler when cross-reference information is being 
saved (that is, when either the XREF option or the XREFFILES option is TRUE). 
Instead, the file XREF/code-file-name, where code-file-name is the name of the object 
code file generated by the compiler, remains on disk. The SYSTEM/KREFANALYZER 
utility can be run later by using the file XREF/code-file-name as input. The 
NOXREFLIST option has no effect if both the XREF option and the XREFFILES option 
are FALSE. 
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See Also 


For more information about cross-reference files, refer to “Using Cross-Reference Files” 
earlier in this section. 


OMIT 


OMIT 


(Type: Boolean, Default: FALSE) 

The OMIT option causes all source-language records, except other compiler control 
records (CCRs), to be ignored (but not discarded) for compilation until the option is 
FALSE. 


This option can appear on a CCR in either the primary (CARD file) or the secondary 
(SOURCE file) source-language input. 


The omitted source-language records are carried forward to the output symbolic file 
(NEWSOURCE file) if the NEW option is also TRUE. The records are not listed unless 
the LISTOMITTED option is TRUE. . 


CCRs encountered in the source-language input while this option is TRUE are processed 
in the normal fashion. 


See Also 


For information on listing that part of the source-language input that was omitted by the 
OMIT option, refer to “LISTOMITTED” earlier in this section. | 


OPTIMIZE or OPT 


(Type: Value, Default: No optimization) 


The OPTIMIZE option applies optional optimization functions that are included at 
appropriate levels during the compilation process. 


OPT and OPTIMIZE are synonymous. 
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The setting of this option cannot be altered after the first source record. 
The setting of this option results in the following actions: | 


e Numerical comparisons involving some unsigned display items are compared as 
characters, rather than being converted to binary items and then compared. The 
zone portion of each character is masked with hex letter F so that uninitialized data 
items compare equal to 0 (zero). 


e Simple ADD statements involving some unsigned display items are executed as 
character additions with all zones masked with hex letter F so that uninitialized data 
items are considered 0 (zero). 


e Invalid index checking on subscripting is bypassed, thus the responsibility for — 
ensuring the validity of any given subscript rests with the programmer. System 
protection against accesses beyond the bounds of the record remains in effect. 


‘e The characteristics of the PERFORM statements and ranges of the program 
are analyzed. If the increase in the amount of object code is not too great, the 
statements in the PERFORM range are expanded in line. 


The use of the USE FOR DEBUGGING statement to monitor items might not always 
work correctly when the OPTIMIZE option is TRUE. Some items in certain statements 
might not be monitored correctly (or at all). _ 


You cannot use the OPTIMIZE option with the TADS, MAKEHOST, and SEPCOMP 
options. If the TADS, the MAKEHOST, or the SEPCOMP option is TRUE or becomes 
TRUE, the compiler sets the OPTIMIZE option to FALSE and issues a warning 
message. 


OWN 


(Type: Boolean, Default: FALSE) 


The OWN option causes all WORKING-STORAGE SECTION data items to assume the 
declaration OWN except those for which LOCAL or GLOBAL is explicitly declared. The 
OWN option is ignored if the compilation is at the 02-level, OWN and GLOBAL options 
cannot. both be TRUE. 


As the compiler parses each data declaration, it checks the setting of the OWN option 
when the current syntactical element is the data-name in the declaration and the next 
syntactical element has been prepared for future analysis. If an ending period follows 

the data-name and the next syntactical element is a CCR that changes the setting of the 
OWN option, the new OWN option setting affects the data item. 


To prevent the new OWN option setting from affecting the data item, redundant clauses 
or semicolons (;) can be inserted in the data declaration that precedes the CCR so that at 
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least one syntactical element exists between the data-name and the ending period of the 
data declaration. 


Unisys recommends not changing the OWN option within the clauses of a data 
declaration. Instead, the option should be changed either before the level number or 
after the ending period of the data declaration. 


The VALUE clause cannot be used with the OWN option. 


OWNTEMP 


OWNTEMP 


(Type: Boolean, Default: FALSE) 

The OWNTEMP option causes the temporary arrays generated by the compiler for 
the processing of some statements to be OWN. The OWNTEMP. and GLOBALTEMP 
compiler control options cannot both be TRUE. The OWNTEMP option is ignored in a 
program compiled at level 2. 


_ This option must appear before the first source record and cannot appear on any 
compiler control record (CCR) after the first source record. 


Note: This option can produce unpredictable errors or results if used in a 


bound procedure that is then used as an asynchronous process (that 
is, by an ALGOL PROCESS statement). 


PAGE 


PAGE 


(Type: Immediate) 
The PAGE option ejects a page on the output listing. 
If the LIST option is FALSE, the PAGE option is ignored. 


If the OMIT option is TRUE and the LISTOMITTED option is FALSE, the PAGE option 
is ignored. 
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SEPCOMP 


SEPCOMP [ ( file-title ) ] 


(Type: Boolean, Default: FALSE) 


The SEPCOMP option separately recompiles selected areas of a previously compiled 
COBOL program. To doa SEPCOMP compilation, you must first compile the program 
with the compiler control option MAKEHOST compilation set to TRUE. This step 
creates the host file. The host file is an executable code file that contains additional 
information necessary fora SEPCOMP compilation. Given only the name of the host 
file, the name of the original source, and the patches to change the source, the compiler 
is able to separately compile the patched areas, resulting in an abbreviated compilation. 
Only the affected areas of the program are actually compiled. 


The file-title must be a quoted string containing a file title. If you do not specify a file 
title, HOST is assumed unless it is preempted by a file equation. 


The SEPCOMP option can be specified only in the compiler file CARD. 


See Also 


For specific information on using the SEPCOMP option, refer to “Performing a Separate 
Compilation” earlier in this section. 


SEQCHECK 


INERROR | 
SEQCHECK [ | OUTEREOR | 


PURGE 


(Type: Boolean, Default: FALSE) 


This option checks the sequence numbers of the primary, secondary, and/or new symbolic 
records to ensure that the numbers are in ascending order in a manner specified by the 
parameters. . 


This option then verifies that the sequence number of the current source-language 
record acquired from the primary input (CARD file) or the secondary input (SOURCE 
file) or directed to the output (NEWSOURCHE file) is greater than the sequence number 
of the previous source-language record acquired from or directed to the same file. 


If the sequence numbers are not in ascending order, a sequencing warning is produced. 
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For the primary input only, if the previous sequence number was made up of spaces and 
if the current sequence number is also made up of spaces, then a sequencing warning is 
not produced. 


The comparison of sequence numbers is done to allow nonnumeric sequence number 
values. 


_ The specification of the parameter INERROR directs the compiler to treat sequencing 
warnings on the primary or secondary inputs as syntax errors. 


The specification of the parameter OUTERROR directs the compiler to treat sequencing 
warnings on the output symbolic file (NEWSOURCE file) as syntax errors. 


The specification of the parameter PURGE directs the compiler to purge the output 


symbolic file (which is not locked or entered into the directory) if sequencing warnings 
occur that refer to the output symbolic file. 


SEQUENCE or SEQ 


{SEQUENCE} 


SEQ 


(Type: Boolean, Default: FALSE) 


The SEQUENCE option assigns new sequence numbers to the source-language records 
accepted for compilation. 


SEQUEN CE and SEQ are synonymous. 


This option affects only input source-language records encountered by the compiler 
following the merging process, including records that were omitted because of the OMIT 
option. 


The SEQCHECK option assigns the current Sequence Base option value to the current 
source-language record and increments the Sequence Base option value by the Sequence 
Increment option value. Sequencing occurs before the production of a new symbolic file 
and before the source-language record is listed. 


If the result base exceeds 999999 when the compiler increments the Sequence Base 


option value by the Sequence Increment option value, then the SEQUENCE option is 
disabled and a sequencing error is produced. 
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Sequence Base 


integer 


(Type: Value, Default: 10) 


The Sequence Base option stores the specified integer value as the Sequence Base 
associated with the SEQUENCE option. 


This option must appear on a CCR so that it is dissociated from any other option that 
requires an integer as a parameter or a value. 


The maximum value of the integer is 999999. 


This option can be specified independently of the SEQUENCE option. 


Sequence Increment 


+ integer 


(Type: Value, Default: 10) 


The Sequence Increment option stores the specified integer value as the Sequence 
Increment associated with the SEQUENCE option. 


This option must appear on a CCR so that it is dissociated from any other option 
requiring a positive integer as a parameter or a value. 


The maximum value of the integer is 999999. 
The plus sign (+) must immediately precede the integer. 


- This option can be specified independently of the SEQUENCE option. 
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SHARING 


SHAREDBYRUNUNIT 
SHAREDBYALL 


PRIVATE 
DONTCARE 


(Type: Value, Default: SHAREDBYRUNUNIT) 


The SHARING option specifies the way in which the program is shared when called as a 
library. Table 17-8 shows the result of settings each SHARING option value. 


Table 17-8. Effects of the SHARING Option 


SHAREDBYRUNUNIT All users of this run unit (the program and any libraries that 
are called) share the same instance of the library. 


SHAREDBYALL All simultaneous users share the same instance of the 
library. 


PRIVATE A separate instance of the library is started for each user. If 

the library can be called by programs other than COBOL74 
programs, consider setting the LIBRARYLOCK option to 
TRUE. 


DONTCARE The sharing is determined by the operating system. 


If the library is called by a COBOL74 program, the library services only one user at a 
time, regardless of the setting of the SHARING option. In a complex environment 
where multiple libraries are linked together, a COBOL74 library with the SHARING 
option set to PRIVATE should also have the LIBRARYLOCK option set to TRUE to 
ensure data integrity. 


See Also 


e For information about the state of a library, refer to “Effect of Library Initial State 
on CANCEL Statement” in Section 15, “Libraries.” 


e For information on locking and sharing libraries, refer to “LIBRARYLOCK” and 
“SHARING,” respectively, earlier in this section. 
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SPEC 


SPEC 


(Type: Boolean, Default: FALSE) 


The SPEC option suppresses printing of warning messages, sequence error messages, 
_ the expansion of the Data Management System II (DMSI1) INVOKE statement, and the 
list of elementary items ina CORRESPONDING option. 


STATISTICS 


STATISTICS 


(Type: Boolean, Default: FALSE) 


The STATISTICS option compiles the source language input so that statistical data 
about the object program is written when the object program is executed. Use of this 
option is designed for a development environment, not a production environment, 
because extra processor overhead is generated. _ 


The STATISTICS option is incompatible with the MAKEHOST. SEPCOMP and 
BINDINFO options. In addition, the STATISTICS option is not valid if the LEVEL 
option has a value greater than 2. 


If the MAKEHOST or the SEPCOMP option is TRUE or becomes TRUE, then the 
STATISTICS option is set to FALSE and a warning message is issued. If an attempt is 
made to set both the STATISTICS and BINDINFO options to TRUE, the first option 
that became TRUE is unaffected, the second option is set to FALSE, and a warning 
message is issued. 
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SUMMARY 


(Type: Boolean, Default: FALSE) 


The SUMMARY option produces a summary listing of appropriate information about the 
compilation. 


The summary produced by this option is the same as that produced when the LIST 


option is set to TRUE. In addition, usage levels of the capacity of the internal tables of 
the compiler are included. 


Symbolic ID 


" alphanumeric literal " 


(Type: Value, Default: None) 


The Symbolic ID option stores the specified alphanumeric literal as the Symbolic ID 
option value associated with the NEWID option. 


The alphanumeric literal cannot be longer than 8 characters. 


This option must appear on a CCR so that it is dissociated from any other option that 
might require a quoted string as a parameter. 


TADS 


Taps |‘ Saree \y| 


REMOTE file-identifier 


(Type: Boolean, Default: FALSE) 

When the TADS option is TRUE, the Test and Debug System (TADS) generates 

special debugging code and tables as part of the Chyect program. The tables support the 
symbolic debugging environment of TADS. 

You must place the TADS option before the first record that is not a CCR in the source 


program. 
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The FREQUENCY option generates additional code and tables for test coverage and 
frequency analysis. You must specify the FREQUENCY option if you want to use the 
TADS commands FREQUENCY or COVERAGE to determine the number of times 
individual statements have been executed or to determine which statements have not 
been executed. 


The REMOTE option allows TADS to share a REMOTE file with the program being 
tested. Sharing a file might be necessary because only one REMOTE input file can be 
open for each station. The file must have been assigned to the REMOTE file identifier, 
and must be opened I-O. The record size must not be less than 72. 


After the compiler reaches the PROCEDURE DIVISION header, if the source file 
contains sequence numbers, the TADS option performs some of the sequence number 
checking associated with the SEQCHECK INERROR compiler control option. 


The sequence numbers of source records must be in ascending order. If this is not the 
case, the compiler issues a syntax error. This rule does not apply to CCRs. 


A CCR can have the same sequence number as the source record that immediately 
precedes or follows it. The compiler issues a syntax error if the sequence number of a 
CCR is less than that of the preceding source record that is not a CCR. 


You cannot use the TADS option with the OPTIMIZE, MAKEHOST, SEPCOMP and | 
BINDINFO options. 


Programs compiled with the TADS option set to TRUE cannot be used as input to the 
Binder. 


See Also 


For more information on debugging COBOL74 programs, refer to the A Series COBOL 
ANSI-74 Test and Debug System ( TADS) Programming Guide. 
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TARGET 


MICROA 
B7900 
B7000 
LEVEL4 
LEVEL2 
LEVEL1 
LEVELO 


(Type: Target, Default: Installation defined) 


The TARGET option generates code suited for a specific computer system or a group of 
systems, and should be used to specify all machines on which the code file needs to run. 


The code file generated is optimized for the machine or the group of machines identified 
by the primary identifier, subject to the compatibility constraints of the machine or 
the group of machines identified by the secondary identifier. That is, the code file is 

_ optimized for the machine or machines listed as the primary identifier, but no operator is 
generated that is not supported by all the machines listed as secondary identifiers. 


The TARGET option identifiers are as follows: 


e A target identifier that names a specific machine (for example, A4) optimizes a code 
file to be run on that machine so that the code file receives the characteristics for 
that machine. 


e The THIS identifier is a synonym for the target identifier of the machine on which 
the code file is compiled. 
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e The ALL identifier indicates that the code file must be able to be run on all currently 
supported machines. Note that the code generated when the TARGET option is 
equal to ALL changes as older machines are no longer supported and as new ones 
are added. LEVEL is presently a synonym for ALL. 


e The B7900 and B7000 identifiers generate code that can be used to run on a 
previously supported Mark release. B7900 and B7000 are synonyms. 


e The LEVEL! and LEVEL2 identifiers encompass the MICROA, A1, A2, A8, A4, A5, 
A6, A12, A15, and A17 target identifiers. 


The LEVEL4 identifier encompasses the A16 target identifier. Code files compiled 
with a primary target identifier of either A16 or LEVEL4 might not run on machines 
other than the A 16. 


- The TARGET option must appear before the first record that is not a compiler control 
record (CCR) in the source program. 


Note: The A16 system runs most code files compiled with Mark 3.7 SR 2 or 
later compilers. 


See Also 


For a description of the COMPILERTARGET command, refer to the A Series System 
Commands Operations Reference Manual. 


TEMPORARY 


(Type: Boolean, Default: FALSE) 


The TEMPORARY option causes the object program, when called as a library, to function 
as a temporary library. This option i is FALSE by default, causing the program to function 
as a permanent library. 


This option is dictated by the value of the SHARING option. A library is made 


permanent only if the SHARING option has been specified as SHAREDBYALL or 
DONTCARE. 


See Also 


e For information on sharing a library, refer to “SHARING” earlier in this section. 


e For information about temporary and permanent BErATIeS) refer to “TEMPORARY” 
in Section 15, “Libraries.” 
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USER 


identifier 


(Type: Boolean, Default: FALSE) 


If an identifier on a compiler control record (CCR) is not recognized as one of the 
standard options, it is considered a USER option. This option must be an alphanumeric 
identifier. 


A user option can be manipulated exactly like any other Boolean option; that is, you can 
set, reset, or pop it. In addition, the USER option can be used as a variable in option 
expressions to assign values to standard Boolean options or to other user options. 


VOID sequence-number 


(Type: Immediate) 

The VOID option discards all input records, except other compiler control records 
(CCRs) in the secondary source-language input file (SOURCE file), until the secondary 
input sequence-number exceeds the specified sequence-number. 

The sequence-number must be an unsigned integer. The sequence-number cannot be 
less than the sequence-number of the CCR on which the VOID option is specified. The 
maximum value of sequence-number is 999999. 

This option can appear only on a CCR in the primary source-language input (CARD file). 
This option is ignored if the MERGE option is FALSE. 


The source-language records that are discarded are not carried forward to the output 
symbolic file (NEWSOURCE file). 


The source-language records that are discarded are not listed unless the LISTDELETED 
option is set. 


See Also 


For information on listing that part of the source language that was deleted by the 
DELETE or VOID options, refer to “ LISTDELETED” earlier in this section. 
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WARNFATAL 


WARNFATAL 


(Type: Boolean, Default: FALSE) 

The WARNFATAL option causes warning messages to be treated as syntax errors. 

The value of the WARNFATAL option when the compiler encounters the end of the 
source file is used during the entire code-generation process. If the option has the value 
TRUE at the end of the source file, any warnings issued during the code-generation _ 


process will be syntax errors even if the particular source records were analyzed when 
the value of the WARNFATAL option was FALSE. 


WARNSUPR 


WARNSUPR 


(Type: Boolean, Default: FALSE) 


The WARNSUPR option suppresses the printing of warning messages only. 


XDECS 


(Type: Boolean, Default: TRUE) 
When the compiler is saving cross-reference information because the XREF option or the 
XREFFILES option is TRUE, only user-defined words declared while the XDECS option 


is TRUE are included in the cross-reference information. If both the XREF option and 
the XREFFILES option are FALSE, the XDECS option has no effect. 


See Also 


For more information about cross-reference files, refer to “Using Cross-Reference Files” 
earlier in this section. . 
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XREF 


(Type: Boolean, Default: FALSE) 
The XREF option causes cross-reference information to be saved by the compiler. 


If the XREF option is TRUE, a listing is produced. If the XREFFILES option is TRUE, a 
pair of disk files is produced. These files are titled XREFFILES/code-file-name/XREFS 
and XREFFILES/code-file-name/XDECS. If both the XREF option and the XREFFILES 
option are TRUE, both a listing and the disk files are produced. 


The XREF option can be used anywhere in the source, but the setting of the option at 
the end of the IDENTIFICATION DIVISION is effective for the entire compilation. Any 
set, reset, or pop of this option after the end of the IDENTIFICATION DIVISION is 
ignored. 


See Also 


For more information about cross-reference files, refer to “Using Cross-Reference Files” 
earlier in this section. 


_XREFFILES 


XREFFILES | 
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(Type: Boolean, Default: FALSE) 


When TRUE, the XREFFILES option causes cross-reference information to 

be saved by the compiler and causes the SYSTEM/XREFANALYZER utility, 

if it is started by the compiler, to produce files that can be used by the Editor 

and the SYSTEM/INTERACTIVEXREF utility. These files have the titles 
XREFFILES/code-file-name/DECS and XREFFILES/code-file-name/REFS, where the 
code-file-name is the name of the object code file that the compiler is generating. 


This option can be used anywhere in the source, but the setting of the option at the end 


of the IDENTIFICATION DIVISION is effective for the entire compilation. Any set, 
reset, or pop of this option after the end of the IDENTIFICATION DIVISION is ignored. 


See Also 


For more information about cross-reference files, refer to “Using Cross-Reference Files” 
earlier in this section. 
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XREFS 


XREFS 


(Type: Boolean, Default: FALSE) 


_ When the compiler is saving cross-reference information because the XREF option or the 
XREFFILES option is TRUE, only references that are found while the XREFS option is 
TRUE are included in the cross-reference information. References to user-defined words 
that are declared when the XDECS option is FALSE are not cross-referenced. If both 
the XREF option and the XREFFILES option are FALSE, then the XREFS option has 
no effect. 


The files produced can be used by the SYSTEM/INTERACTIVEXREF utility or by the 
Editor. The titles of the files produced are XREFFILES/code-file-name/DECS and 
XREFFILES/code-file-name/REFS , where the name of the code file is produced by the 
compiler. . 


Generation of the interactive XREFFILES file is inhibited if the NOXREFLIST option is 
TRUE. 


See Also 


For more information on cross-reference files, refer to “Using Cross-Reference Files” 
earlier in this section. 


8600 0296-000 7 os | | 17-47 


17-48 . 8600 0296-000 


Appendix A 
General Format Notation 


General format notations are syntax diagrams that show the rules for creating 
COBOL74 code from words and symbols. These format notations visually represent the 
valid combinations of words and symbols that make COBOL74 statements or clauses. 


To familiarize you with format notations, this appendix describes the components of 
the general format notation and provides examples of using format notations to create 
COBOL74 entries. You can refer to the examples at the back of this appendix as you 
read the explanation of each component of the general format notation. 


All the format notations, whether simple or complex, follow the same basic rules. Once 
you understand them, the format notations serve as quick references to the syntax for 
statements and clauses. 


The general format notation shows you the following: 


e Required words and optional keywords 

e Words you must provide 

© The order in which the items must appear 

e Entries that can be repeated 

e Required and optional punctuation 

When more than one format notation appears for a statement or clause, each format 
describes the valid combinations of COBOL74 code for a particular application. For 


example, there are three separate formats for three separate types of addition. The 
formats are numbered and labeled for ease of reference. 


You can construct COBOL74 statements and clauses from the components shown in 

_ the following list. Some components represent words that you use in your code. Other 
components symbolize the rules for constructing your code. For example, you include 
uppercase underlined words in your code. You do not include the braces and brackets in 
your code. Instead, these symbols indicate alternatives and options for the words they 
enclose. 
e Uppercase words 
e Lowercase words 
e Level numbers 
e Braces ({}) 
e Brackets ({]) _ 


e Ellipses (...) 
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° Separators 

e Special characters 

You must code the words in the order in which they appear in the general format. The © 
words can appear in a different order only if it is explicitly stated in the explanation of 
the format that you can do so. 


Table A~1 shows each component of the format notation and explains its meaning. 


Table A-1. General Format Notation Components 


Components | Explanation 


Underlined uppercase Identify required words that you must include in the statement or 
words clause. 


Not underlined Show optional keywords that you can include or omit without 
uppercase keywords affecting the meaning of the statement or clause. An optional word 
enclosed in braces indicates a default option. 


Lowercase words Indicate words that you must supply. If you see a number appended 
to a lowercase word, that lowercase word represents a particular 
occurrence of that word. 


Level numbers Describe numbers that you must provide to show the organization of 
your data. 
{} (Braces) ‘ Enclose a group of phrases stacked vertically from which you must 


pick only one. If braces enclose a single phrase, you can repeat the 
phrase. If braces enclose multiple phrases, you must pick one 
phrase from the list of alternatives. 


(] (Brackets) Enclose a group of phrases stacked vertically that are optional. If 
brackets enclose a single option, you can omit that option. If 
brackets enclose multiple options, you can omit all the options or 
you can pick one option from the list of options. Phrases with 

phrases are allowed. Nested phrases appear enclosed in braces or 

brackets within another phrase enclosed in braces or brackets. 


... (Ellipses) Represent the point at which you can repeat a part of the format. 
Ellipses can appear only immediately to the right of a right bracket 
or a right brace. The part of the format that you can repeat is the 


part enclosed within the preceding brackets or braces. 


Separators Indicate punctuation in a sentence. Table 3-2 lists all the 
separators. Commas and semicolons are optional. You can use 
separators between statements if you want. (You can interchange 


the comma, semicolon, and space characters.) 


Periods are required. You must end with a period the paragraphs 
within the IDENTIFICATION and PROCEDURE DIVISIONS and 
entries within the ENVIRONMENT and DATA DIVISIONS. 


t Unisys extension — continued 
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Table A-1. General Format Notation Components (cont.) 


Components Explanation 


Special characters Indicate arithmetic operations or relation conditions. Special 
characters are not underlined in the general format notation. 


However, if a special character appears, it is required. The special 
characters include the symbols for addition, subtraction, 
multiplication, division, and exponentiation (+, -, *, /, **) and the 
symbols for less than, equal to, and greater than (<, =, >). 


Example 1 


The following example is the general format notation for the BLOCK clause: 


BLOCK CONTAINS [ integer-1 TO ] integer-2 rere } 


CHARACTERS 


Explanation 
This example illustrates the following: 


~e@ BLOCK isa word that you must enter. 
e CONTAINS is an optional keyword for improving readability. 
e The integer-1 TO phrase is optional. If it is used, TO is required. 
e Integer-2 isa required entry. You must substitute a number for integer-2. 


e CHARACTERS is the default phrase. If you do not enter either RECORDS or 
CHARACTERS, the compiler assumes CHARACTERS. However, you can enter 
CHARACTERS to improve the readability of your code. If you do not want 
characters and do want records, then you must enter RECORDS. 


Using the preceding format notation, you can code any of the following lines. Notice that 
all three lines of code are equivalent to the compiler, but the full notation is clearer to an 
outside reader. 


BLOCK CONTAINS 488 TO 588 CHARACTERS 
- BLOCK CONTAINS 488 T@ 508 
BLOCK 488 TO 586 


You can also code the following line. In this instance, you can choose not to use the 
integer-1 TO option and you can choose RECORDS. 


BLOCK CONTAINS 15 RECORDS 
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Example 2 


The following example is the general format notation for the COMPUTE statement: 


COMPUTE identifier-1 [ ROUNDED ] | , identifier-2 [ ROUNDED ] ] ... 


= arithmetic-expression | ; ON SIZE ERROR imperative-statement | 


Explanation 
This example illustrates the following: 


e COMPUTE is a word that you must enter. 
e Identifier-1 and arithmetic-expression are entries that you must provide. 


e ROUNDED is an option. If you choose to use it, your results are arithmetically 
rounded. . 


e ,identifier-2 is an option. It can be repeated with or without the ROUNDED option. 
e The equals sign and period are required. 
e The comma and semicolon are optional. 


e ; ON SIZE ERROR imperative-statement is an option. If you choose to use this 
option, the phrase, ON is optional, but SIZE, ERROR, and imperative-statement are 
required. 


Two valid statements that you could form are the following: 


COMPUTE fruit-inventory = apples + oranges + bananas. 
COMPUTE ws-fruit, print-fruit ROUNDED = fruit-inventory + order-size. 
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Reserved Words and Keywords 


This section describes and lists the reserved words and the keywords provided in Unisys 
COBOL74. 


Reserved Words 


A reserved word can never be declared as an identifier. Its predefined meaning cannot 
be changed. os 


Following is the list of reserved words. Words that are reserved but are described in 
Volume 2 of this manual are also included. 


A 

_ABORT-TRANSACTION ACCEPT ACCESS 

ADD ADVANCING AFTER 

ALARM ALL ALLOW 

ALPHABETIC ALSO ALTER 

ALTERNATE AND ARE 

AREA AREAS ASCENDING 

ASSIGN AT ATTACH 

AUDIT AUTHOR 

B 

BEFORE BEGIN-TRANSACTION BEGINNING 

BINARY BLANK — BLOCK 

BOTTOM BY 

| Cc 

CALL CANCEL CAUSE 

CD CF CH 

CHANGE CHARACTER CHARACTERS 

CLOCK-UNITS CLOSE CMP 

COBOL CODE CODE-SET 

COLLATING COLUMN _ COMMA 

COMMANDKEYS COMMUNICATION “COMP 

COMPUTATIONAL COMPUTE CONFIGURATION 

CONTAINS CONTENT CONTINUE 

CONTROL CONTROL-POINT CONTROLS 

: continued 
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COPY 


CORRESPONDING 


CREATE 
CURRENT 


DATA 
DATE-COMPILED 
DB 
DEBUG-ITEM 
DEBUG-SUB-1 
DEBUGGING 
DELETE 
DEPENDING 
DETACH 
DISABLE 
DISPLAY 


.DMERROR 


DMTERMINATE 


~ DOWN 


EGI 
ENABLE 
END-TRANSACTION 
EOP 

ESI 

EXCEPTION 

EXIT 


FALSE 
FILE 
FINAL 
FOOTING 


-FORM-KEY 


FUNCTION 


Cc 


- COPY-NUMBER 


COUNT 
CRUNCH 


D 
DATA-BASE | 
DATE-WRITTEN 
DE 
DEBUG-LINE 
DEBUG-SUB-2 
DECIMAL-POINT 
DELIMITED 
DESCENDING 
DETAIL 
DISALLOW 
DIVIDE 
DMSTATUS 
DMUPDATECOUNT 
DUPLICATES 

E 
ELSE 
END 
ENDING 
EQUAL 
EVENT 
EXCLUSIVE 
EXTEND 


FD 
FILE-CONTROL 
FIND 

FOR 

FREE 


CORR 
CP 
CURRENCY 


DATE 

DAY 
DEBUG-CONTENTS 
DEBUG-NAME 
DEBUG-SUB-3 
DECLARATIVES 
DELIMITER 
DESTINATION 
DICTIONARY 
DISK 

DIVISION 
DMSTRUCTURE 
DOUBLE 
DYNAMIC 


EMI 
END-OF-PAGE 
ENVIRONMENT 
ERROR 

EVERY 
EXECUTE 
EXTERNAL 


FIELD 
FILLER 
FIRST 
FORM 
FROM 
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GENERATE 
GREATER 


HEADING 


I-0 
IDENTIFICATION 
INDEX 

INITIAL 

INPUT 

INSERT 
INTERRUPT 
INVOKE 


JUST 
KANJI 


LABEL 

LEADING 

LESS 

LINAGE 
LINE-COUNTER 
LOCAL — 
LOCKED 
LOWER-BOUND 


MEMORY 


MID-TRANSACTION 


MOVE 


NATIVE 
NO 

NOT 
NUMERIC 
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GIVING 
GROUP 

H 
HIGH-VALUE 
|-O-CONTROL 
IF 
INDEXED 
INITIALIZE 
INPUT-OUTPUT 
INSPECT 
INTO 
Is 


JUSTIFIED 
KEY 
LAST 


LEFT 
LIMIT 


LINAGE-COUNTER 


LINES 
LOCAL-STORAGE 


._LOW-VALUE 


LOWER-BOUNDS 
M 

MERGE 

MODE 

MULTIPLE 
ON 

NEGATIVE 

NO-AUDIT 

NULL 


GO 


HIGH-VALUES 


ID 


_IN 


INDICATE 
INITIATE 
INQUIRY 
INSTALLATION 
INVALID 


LD 
LENGTH 
LIMITS 

LINE 
LINKAGE 
LOCK 
LOW-VALUES 


MESSAGE 
MODULES 
MULTIPLY 


NEXT 
NONE 
NUMBER 
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OBJECT-COMPUTER 
ODT-INPUT-PRESENT 


OFFSET 

OPEN 
ORGANIZATION 
OWN 


PAGE 
PERFORM 
PIC 

POINT 
POSITIVE 
PROCEDURE 
PROCESS 
PURGE 


QUEUE 


RANDOM 


READ-OK 
RECEIVE 
RECORDS 
REEL 
REFERENCES 
REMAINDER 
RENAMES 
REPORTING 
RESERVE 
REVERSED 
RF. 
ROUNDED 


SAME 
SEARCH 
SECURITY 


SEGMENT-LIMIT 


ole 
OF 
OMITTED 
OPTIONAL 
OUTPUT 


P 
PAGE-COUNTER 
PF 
PICTURE — 
POINTER 
PRINTING 
PROCEDURES 
PROGRAM 


QUOTE 


RD 
READ-WRITE 
RECEIVED 
RECREATE 
REF 
RELATIVE 
REMOVAL 
REPLACING 
REPORTS 
RESET 
REWIND 
RH 

RUN 


SAVE 
SECTION 
SEEK 
SELECT 


OCCURS 
OFF 

ON 

OR 
OVERFLOW 


PC 

PH 

PLUS 
POSITION 
PRIOR 
PROCEED 
PROGRAM-ID 


QUOTES 


READ 

REAL 
RECORD 
REDEFINES 
REFERENCE 
RELEASE 
REMOVE 
REPORT 


RERUN 


RETURN 
REWRITE 
RIGHT 


SD 
SECURE 
SEGMENT 
SEND 


continued 
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SENTENCE 
SEQUENTIAL 
SINGLE 
SORT-MERGE 
SPACE 

STACK 

START 

STORE 
SUB-QUEUE-2 
SUM 
SYNCHRONIZED 


TABLE 
TALLYING 
TERMINAL 
THAN 

THRU 

TIMES 
TODAYS-NAME 
TRAILING — 
TRUE 


UNIT 

UNTIL 
UPON 
‘USING 


VA 
VARYING © 


WAIT 
WORDS 


WRITE-OK 


ZERO 
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. S 
SEPARATE 
SET 

SIZE 

SOURCE 
SPACES 
STANDARD 
STATUS 
STRING 
SUB-QUEUE-3 
SYMBOLIC 
SYSTEM 


TAG-KEY 
TASK 
TERMINATE 
THEN 


_ TIME 


TO 

TOP 
TRANSACTION 
TYPE 


UNLOCK 
UP 
USAGE 


WHEN 
WORKING-STORAGE 


zZ 
ZEROES 


SEQUENCE 

SIGN 

SORT 
SOURCE-COMPUTER 
SPECIAL-NAMES 
STANDARD-1 

STOP 

SUB-QUEUE-1 
SUBTRACT 

SYNC 


_SYSTEMERROR 


TAG-SEARCH 
TB 

TEXT 
THROUGH 
TIMER 
TODAYS-DATE 
TRACTORS 
TRANSPORT 


UNSTRING 
UPDATE 


USE 


VALUES 


WITH 
WRITE 


ZEROS 
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See Also 


For further information about product-specific extensions of these words, refer to 
Volume 2 of this manual. 


Context-Sensitive Keywords 


A context-sensitive keyword can be redeclared as an identifier, and if it is used where the 
syntax calls for that reserved word, it carries the predefined meaning; otherwise, it has 
the user-declared meaning. 


The following are the context-sensitive keywords: 


Application-Specific Keywords 
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AREAOVERFLOW HERE SW3 
ASCII INTEGER SWw4 
| BACKUP KEYSPERENTRY SW5 

CAPABLE LIST SW6 
CATEGORY MOD SW7 
CHANNEL ODT SW8 

COLON OPEN SWw9 
CONVERSATION PORT TAPE 
DBKIND PRINTER TAPES 
DEFAULT PRODUCTION TEMPORARY 
DIV PUNCH TEST 

DMSII READER TITLE 
DMEXCEPTIONMSG REM TRUNCATED 
DMNEXTEXCEPTION REMOTE URGENT 
DUMP SEMANTIC USER 
EBCDIC SPO VERSION 
ERRORTYPE STRUCTURE WFL 
FILEOVERFLOW sw] WHERE 
HEADER SWw2 


An application-specific keyword is reserved by the compiler for the extent of the program 
when you are using a SIM or some network applications. 


The compiler reserves the following words in programs only when you specify the 
RESERVE NETWORK clause in the SPECIAL-NAMES paragraph. 


AWAIT-OPEN 
"RESPOND 
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Reserved Words and Keywords 


See Also 


Refer to Volume 2 of this manual for the list of words the compiler reserves when you 
specify the RESERVE SEMANTIC clause in the SPECIAL-NAMES paragraph. 
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Appendix C 
EBCDIC and ASCII Character Sets 


Tables C—1 and C-2 list the hexadecimal representation and ordinal number for each 
ASCII and EBCDIC character. Table C-1 is sorted by EBCDIC ordinal number and 
represents the EBCDIC-to-ASCII translation performed when necessary. Table C-2 
is sorted by ASCII ordinal number and represents the ASCII-to-EBCDIC translation 
performed when necessary. 


Note: In the following tables, any ASCII character greater than 127 (4"7F") 
is not valid. 


Table C-1. EBCDIC-to-ASCII Translation Chart 


EBCDIC | ASCII 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Null 
Start of Heading 
Start of Text 
End of Text 


Horizontal 
Tabulation 


Delete 


Vertical Tabulation 
Form Feed 
Carriage Return ° 
Shift Out 
Shift In 


continued 
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C-2- 


Table C~1. EBCDIC-to-ASCIl Translation Chart (cont.) 


. EBCDIC . ASCII 


Hex Ordinal Hex _ Ordinal 
Code Number Code Number Char Description 


Data Link Escape 


— Device Control 1 
Device Control 2 


Device Control 3 


Backspace 


Cancel 
End of Medium 


File Separator 
Group Separator 
Record Separator 


Unit Separator 


Line Feed 


End of 
Transmission 
Biock 


Escape 


continued 
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EBCDIC and ASCII Character Sets 


Table C-1. EBCDIC-to-ASCII Translation Chart (cont.) 


EBCDIC ASCII 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Enquiry 
Acknowledge 


Bell 


Synchronous Idle 


End of 
Transmission 


Device Control 4 


Negative 
Acknowledge 


Substitute 


Space 


continued 
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Table C-1. EBCDIC-to-ASCII Translation Chart (cont.) 


EBCDIC ASCII 


Hex * Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Opening Bracket 


Period 


Less Than 


Opening 
Parenthesis 


Plus 
4F 79 mee 33 ! ~ Exclamation Point 
50 80 26 38 Ampersand | 


Closing Bracket 
Dollar Sign 
Asterisk 


5D 93 29 41 ) Closing 
. Parenthesis 


continued 
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EBCDIC and ASCII Character Sets 


Table C-1. EBCDIC-to-ASCII Translation Chart (cont.) 


EBCDIC - ASCII 


Hex | Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Semicolon 


Circumflex (ASCII); 
Not Sign (EBCDIC) 


Hyphen (Minus) 
Slant (Slash) 


Vertical Line 
Comma 
Percent 
Underline 
Greater Than 


Question Mark 


continued 
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Table C-1. EBCDIC-to-ASCII Translation Chart (cont.) 


EBCDIC ASCII 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Grave Accent 
(Opening Single 
Quotation Mark) 


Colon 


Number Sign 


Commercial At 


Apostrophe 
(Closing Single 
Quotation Mark) 


Equals 
Quotation Marks 
80 128: C3 195 . 

81 129 61 97 Lowercase a 
Lowercase b 
Lowercase c 
Lowercase d 
Lowercase e 
Lowercase f 
Lowercase g 
Lowercase h 


Lowercase i 


Lowercase j 


continued 
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Table C-1. EBCDIC-to-ASCII Translation Chart (cont.) 


EBCDIC ; ASCII | 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Lowercase k 


Lowercase | 
Lowercase m 
Lowercase n 
Lowercase O 
Lowercase p 
Lowercase q 


Lowercase r 


Overline (Tilde) 
Lowercase s 
Lowercase t 
Lowercase u 
Lowercase v 
Lowercase w 
Lowercase x 


Lowercase y 


Lowercase Z 


continued 
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Table C-1. EBCDIC-to-ASCII Translation Chart (cont.) 


EBCDIC ASCII . 


Hex — Ordinal Hex Ordinal | 
Code Number Code Number Char Description 


Opening Brace 


Uppercase A 
Uppercase B 
Uppercase C 
Uppercase D 
Uppercase E 
Uppercase F 
Uppercase G 


rc Oo nm OUND DWeOODLPP 


Uppercase H . 


continued 
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Table C-1. EBCDIC-to-ASCII Translation Chart (cont.) 


EBCDIC ASCII | 
Hex Ordinal Hex Ordinal 
Code . Number Code Number. Char Description 


Uppercase | 


DO 208 7D 125 


} Closing Brace 
D1 209 4A 74 J Uppercase J 
D2 210 4B 75 K Uppercase K 
D3 211 AC 76 L Uppercase L 
D4 212 4D 77 M Uppercase M 
D5 213 4E 78 N Uppercase N 
D6 214 4F 79 - 0) Uppercase O 
D7 215 50 80 P Uppercase P 
D8 216 51 . 81 Q Uppercase Q 
D9 217 52 82 R Uppercase R 


Reverse Slant 


Uppercase S 
Uppercase T 


continued 
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Table C-1. EBCDIC-to-ASCIli Translation Chart (cont.) 


EBCDIC . ASCII ° 
Hex Ordinal Hex Ordinal 
Code - Number Code Number Char Description 


E4 228 55 85 Uppercase U 
E5 229 56 86 Uppercase V 
E6 . 230 57 87 Uppercase W 


E7 231 58 88 
E8 232 59 89 


. Uppercase X 


Uppercase Y 


N << S$ < Cc 


Uppercase Z 


Oo AN HD oO BP W DH KF OO 


continued 
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Table C-1. EBCDIC-to-ASCII Translation Chart (cont.) 


| EBCDIC ASCII 


Ordinal Hex Ordinal 


Table C~2. ASCII-to-EBCDIC Translation Chart 


| ASCII EBCDIC | 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Null 
Start of Heading 
02 02 S STX Start of Text | 

End of Text 


End of 
Transmission 


Enquiry 
2E . 46 ACK Acknowledge 
BEL Bell 

16 22 BS Backspace 


05 5 HT Horizontal 
Tabulation 


06 
07 
08 
09 


oO ON OD Ww 
NO 
11 
- 
N 


Line Feed 
Vertical Tabulation 
Form Feed 
Carriage Return 
Shift Out 
Shift In 
Data Link Escape 


continued 


8600 0296-000 . C-11 


EBCDIC and ASCII Character Sets 


C-12 


Table C-2. ASCII-to-EBCDIC Translation Chart (cont.) 


ASCII. | EBCDIC | 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Device Control 1 
Device Control 2 
Device Control 3 


Device Control 4 


Negative 
Acknowledge 


Synchronous Idle 


End of 
Transmission 
Block 


Cancel 
End of Medium 
Substitute 


Escape 


File Separator 
_ Group Separator 
Record Separator 
Unit Separator 
Space 
Exclamation Point 
Quotation Marks 
Number Sign 
Dollar Sign 
Percent 


Ampersand 


Apostrophe 
(Closing Single 
Quotation Mark) 


continued 
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Table C-2. ASCII-to-EBCDIC Translation Chart (cont.) 


ASCII EBCDIC _ | 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Opening 
Parenthesis 


Closing 
Parenthesis 


Asterisk 
Plus 
Comma 
Hyphen (Minus) 
Period 
Slant (Slash) 


Zero 
One 
Two 
Three 
Four 
Five 
Six 
Seven 
Eight 


Oo ON DO FP WN KF ODO ™ 


Nine 


Colon 
Semicolon 
Less Than 
Equals 
Greater Than 
Question Mark 
Commercial At 


Uppercase A 


continued 
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Table C-2. ASCli-to-EBCDIC Translation Chart (cont.) 


ASCII EBCDIC . 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


B Uppercase B 
43 67 C3 195 C Uppercase C 
44 68 | C4 | 196 D Uppercase D 
45 69 C5 197 E Uppercase E 
46 70 C6 198 F Uppercase F 
47 71 C7 199 G Uppercase G 
48 72 C8 200 H Uppercase H 
49 73 C9 201 | Uppercase | 
4A 74 Di 209 J Uppercase J 


Uppercase K 
Uppercase L 
Uppercase M 
Uppercase N- 
Uppercase O 
Uppercase P 
Uppercase Q 
Uppercase R 
Uppercase S 

' Uppercase T 
Uppercase U 

Uppercase V 

Uppercase W 

Uppercase X 

Uppercase Y 


N <~ * S$ < GC AY DD DVO 2 FB - *K 


‘Uppercase Z 
5B 91 4A 74 


| ome | 


Opening Bracket 


continued 


8600 0296-000 


EBCDIC and ASCII Character Sets 


Table C-2. ASCII-to-EBCDIC Translation Chart (cont.) 


ASCIL | EBCDIC 


Hex Ordinal Hex Ordinal 
Code Number Code Number Char Description 


Reverse Slant 
Closing Bracket 


Circumflex (ASCII); 
Not Sign (EBCDIC) 


Underline 


Grave Accent 
(Opening Single 
Quotation Mark) 


Lowercase a 
Lowercase b 
Lowercase c 
64 100 84 132 Lowercase d 
65 101 85 133 e Lowercase e 
Lowercase f 
Lowercase g 


Lowercase h 


Lowercase i 
Lowercase j 
Lowercase k 
Lowercase | . 


Lowercase m 


Lowercase n 
Lowercase 0 
Lowercase p 
Lowercase q 
Lowercase r 
_ Lowercase s 


Lowercase t 


continued 
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_ Table C-2. ASCII-to-EBCDIC Translation Chart (cont.) 


ASCII . EBCDIC 


Hex Ordinal Hex Ordinal . 
Code Number Code Number Char Description 


Lowercase U 


Lowercase V 


Lowercase W 


Lowercase X 
Lowercase y 
Lowercase Z 


| Opening Brace 


Vertical Line 


Closing Brace 


Overline (Tilde) 


Delete. 


8600 0296-000 


_ Appendix D 
Examples 


Following are a group of examples that show various constructs. 


Example 1 


Example D~1 shows a way to read records from a data file and print them out ona 
printer. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. EXECTEST. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. A-9. 
OBJECT-COMPUTER. A-9. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT OPTIONAL CURRFILE 
ASSIGN TO DISK. 
SELECT PFILE ASSIGN TO PRINTER. 
DATA DIVISION. 
FILE SECTION. 
FD CURRFILE 
BLOCK CONTAINS 6@ CHARACTERS 
RECORD CONTAINS 6 CHARACTERS. 
@1 SOURCE-IN-REC. 
@5 SOURCE-IN PIC X(52). 
@5 SOURCE-SEQ PIC 9(8). 
FD PFILE RECORD CONTAINS 64 CHARACTERS. 
@1 PRINT-REC. | , 
@5 PRINT-LINENUM PIC 9(2). 
@5 BLANK-SPACES PIC X(2). 
@5 PRINT-DATA PIC X(52). 


@5 PSEQ PIC 9(8). 
WORKING-STORAGE SECTION. 
@1 LINE-NUMBER: PIC 9(8). 
@1 WSREC. 
25 WSNUM PIC 9(2). 
Q5 WSPAC PIC X(2). 
@5 WSIN PIC X(52). 
B5 WSEQ PIC 9(8). 
PROCEDURE DIVISION. 
PARA-1. 


OPEN INPUT CURRFILE. 


Example D-1. Coding READ and WRITE Statements 
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OPEN OUTPUT PFILE. 
MOVE SPACES TO WSPAC. 
MOVE 1 TO LINE-NUMBER. 
PARA-2. | 
READ CURRFILE AT END GO TO EOJ. 
MOVE LINE-NUMBER TO WSNUM. 
MOVE SOURCE-IN TO WSIN. 
MOVE SOURCE-SEQ TO WSEQ. 
WRITE PRINT-REC FROM WSREC. 
ADD 1 TO LINE-NUMBER. | 


GO TO PARA-2. 
EQJ. 
CLOSE CURRFILE. CLOSE PFILE. 
STOP RUN. 
Example D-1. Coding READ and WRITE Statements (cont.) 
Example 2 


Example D-2 shows the use of indexed files with alternate keys. — 


D-2 


IDENTIFICATION DIVISION. 
PROGRAM-ID. IND-EXMPL. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE~COMPUTER. AQ. 
OBJECT-COMPUTER. AQ. 
INPUT-OUTPUT SECTION. 
FILE-~CONTROL. 
SELECT KENNEL-FILE ASSIGN TO DISK 
_ ORGANIZATION IS INDEXED 
ACCESS MODE IS RANDOM 
RECORD KEY IS NAME 
ALTERNATE RECORD KEY IS COLOR WITH DUPLICATES 
ALTERNATE RECORD KEY IS BREED WITH DUPLICATES. 
SELECT PRINT-FILE ASSIGN TO PRINTER. 


DATA DIVISION. 

FILE SECTION. 

FD KENNEL-FILE BLOCK CONTAINS 6 RECORDS 
VALUE OF TITLE IS "KENNEL/RECORDS". 

81 KENNEL-RECORD. 


@5 NAME . PIC X(12). 
85 COLOR PIC X(1@). 
85 BREED PIC X(1@). 
85 PRICE PIC 9999.99. 
85 KENNEL PIC X(1@). 


@5 KENNEL-NUMBER PIC 9999. 
FD PRINT-FILE. 
81 PRINT-RECORD. 


Example D-2. Coding Indexed Files with Alternate Keys 
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@5 PRINT-ITEM 
@5 PRINT-TRAIL 


PIC 
PIC 


WORKING-STORAGE SECTION. 


X(12) OCCURS 6 TIMES 
X(8). 


01 RED PIC X(19) 

81 TAN PIC X(19) 

@1 BLACK PIC X(19) 

G1 EXPENSIVE PIC 999V99 

81 CHEAP PIC X(19) 

61 NO-SALE PIC X(19) 
PIC 


G1 INDEX-TYPE 


PROCEDURE DIVISION. 
SECTION-1 SECTION. 


PROCEDURE-1. 


OPEN OUTPUT KENNEL-FILE. 


PROCEDURE-2. 


* 


* 


This procedure opens an 
alternate keys and then 


MOVE "OTTO" TO NAME. 
MOVE EXPENSIVE TO PRICE. 
MOVE 13 TO KENNEL-NUMBER. 
WRITE KENNEL-RECORD; 
INVALID KEY DISPLAY 


MOVE "GERONIMO" TO NAME. 
MOVE 358.88 TO PRICE. 
MOVE 97 TO KENNEL-NUMBER. 
WRITE KENNEL-RECORD; 
INVALID KEY DISPLAY 


MOVE "CHARLIE" TO NAME. 

MOVE CHEAP TO PRICE. 

MOVE @1 TO KENNEL-NUMBER. 

WRITE KENNEL-RECORD; 
INVALID KEY DISPLAY 


CLOSE KENNEL-FILE SAVE. 


PROCEDURE-3. 


* 


* 
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This 
data 
OPEN I-O KENNEL-FILE. 
MOVE 


MOVE 
READ 


"RED" TO COLOR. 


MOVE 
MOVE 
MOVE 
"ERROR 


MOVE 
MOVE 
MOVE 


"ERROR 
MOVE 
MOVE 
MOVE 


"ERROR 


"COLOR" TO INDEX-TYPE. 
KENNEL-FILE KEY IS COLOR 


INDEXED BY J. 


VALUE IS 
VALUE IS 
VALUE IS 
VALUE IS 
VALUE IS 
VALUE IS 


it RED" - 
"SPOTTED". 
"BLACK". 
800.00. 
"CHEAP". 
"NO SALE". 


X(1@) DISPLAY. 


OPEN OUTPUT PRINT-FILE. 


indexed file with 
writes data into it. 


"GOLDEN" TO COLOR. 
BLACK TO KENNEL. 
"COLLIE" TO BREED. 


- PRIMARY KEY NOT UNIQUE". 


RED TO COLOR. 
"ANOTHER" TO KENNEL. 
"RETRIEVER" TO BREED. 


- PRIMARY KEY NOT UNIQUE". 


"WHITE" TO COLOR. . 
"NONE" TO KENNEL. 
"MIXED" TO BREED. 


~ PRIMARY KEY NOT UNIQUE". 


procedure opens an indexed file, reads 
with alternate keys and writes to a printer file. 


INVALID KEY PERFORM INVALID-READ-MARKER GO TO G3. 


_ Example D-2. Coding Indexed Files with Alternate Keys (cont.) 
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Examples 


PERFORM WRITE-OUT-RECORD. 


G3. MOVE "MIXED" TO BREED. 
MOVE "BREED" TO INDEX-TYPE. 
READ KENNEL-FILE KEY IS BREED 
INVALID KEY PERFORM INVALID-READ-MARKER GO TO Gl. 
PERFORM WRITE-OUT-RECORD. 


Gl. MOVE "WHITE" TO COLOR. 
MOVE "COLOR" TO INDEX-TYPE. 
READ KENNEL-FILE KEY IS COLOR 
INVALID KEY PERFORM INVALID-READ-MARKER GO TO G2. 
PERFORM WRITE-OUT-RECORD. 
G2. STOP RUN. 


WRITE-OUT-RECORD. 
MOVE SPACES TO PRINT-RECORD. 
MOVE NAME TO PRINT-ITEM(1). 
MOVE COLOR TO PRINT-ITEM(2). 
MOVE BREED TO PRINT-ITEM(3) . 
MOVE PRICE TO PRINT-ITEM(4). 
MOVE KENNEL TO PRINT-ITEM(5). 
MOVE KENNEL-NUMBER TO PRINT-ITEM(6). 
WRITE PRINT-RECORD. 


INVALID-READ-MARKER. 
DISPLAY "ERROR - NO SUCH " INDEX-TYPE " IN FILE" 
MOVE "INVALID RECORD ACCESS" TO PRINT-RECORD. 


Example D-2. Coding Indexed Files with Alternate Keys (cont.) 


Example 3 


Example D-3 shows the use of the OCCURS DEPENDING ON phrase in a WRITE 
FROM statement. This phrase enables the program to vary the length of the record 
to be stored. For example, the length of the record PRINT-ODO-ITEM varies from 1 
through 13, depending on the length of the record PRINT-SUB. 


After execution of this program, the external file PRINT-FILE contains two records. 
The first records contains the characters 13 followed by 130 occurrences of the letter A. 
The second record contains the characters 03 followed by three occurrences of the string 
1234567890: Note that the value contained in the record PRINT-SUB prior to the 
execution of the statement WRITE PRINT-RECORD FROM ODO does not determine 
the number of occurrences of PRINT-ODO-ITEM written to FILEA. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. ODO-EXAMPLE. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER.  B/998. 
OBJECT-COMPUTER. B798@. 


Example D-3. Coding OCCURS DEPENDING ON Phrase in WRITE FROM Statement 
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INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT FILEA ASSIGN TO PRINTER. 
DATA DIVISION. 
FILE SECTION. 
FD FILEA 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS PRINT-RECORD. 
@1 PRINT-RECORD. 
G2 PRINT-SUB PIC 99. 
@2 PRINT-ODO-GROUP. 
@3 PRINT-ODO-ITEM OCCURS 1 TO 13 
TIMES DEPENDING ON PRINT-SUB. 
G4 PRINT4 PIC X(4) . 
@4 PRINT6 PIC X(6) . 
WORKING-STORAGE SECTION. 
91 ODO. 
O2 ODO-SUB PIC 99. 
@2 ODO-GROUP. 
@3 ODO-ITEM OCCURS 1 TO 5 TIMES 
DEPENDING ON ODO-SUB. 
G4 OD06 PIC X(6). 
4 oD04 PIC X(4). 
PROCEDURE DIVISION. 
Pl. 
OPEN OUTPUT FILEA. 
MOVE 13 TO PRINT-SUB. 
MOVE ALL "A" TO PRINT-ODO-GROUP. 
WRITE PRINT-RECORD. 
P2s. -. 
MOVE 3 TO ODO-SUB. 
MOVE 2 TO PRINT-SUB. 
MOVE ALL "1234567898" TO ODO-GROUP. 
WRITE PRINT-RECORD FROM ODO. 
CLOSE FILEA. 


P3. 
STOP RUN. 


Example D-3. Coding OCCURS DEPENDING ON Phrase in WRITE FROM Statement 
(cont.) 


Example 4 


Example D-4 shows a Sort program with the USING and GIVING options. In this 
example, the files that are directly involved in the sort operation must not be open 
when the SORT statement is encountered, because the USING and GIVING options 
perform the functions of the INPUT PROCEDURE and the OUTPUT PROCEDURE 
clauses automatically. Although the use of the GIVING and USING options requires a 
minimum amount of coding, it is not possible to select, add, modify, or delete individual 
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Examples 


records of the sort file in any way. This means that no special processing records can be 


incorporated into a sort function when these options are used. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. SORTB. 


THIS SORT PROGRAM EXAMPLE ILLUSTRATES 
Pi THE FOLLOWING SORT OPTIONS 

* USING 

* GIVING. 


ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. B7929. 
OBJECT-COMPUTER. B7988. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 


SELECT INDATA ASSIGN TO DISK. 
SELECT SORTED ASSIGN TO DISK. 
SELECT WORKFL ASSIGN TO SORT DISK. 
SELECT PRFILE ASSIGN TO PRINTER. 


DATA DIVISION. 
FILE SECTION. 
FD INDATA 
BLOCK CONTAINS 6@ CHARACTERS 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS A-FILE. 
@1 A-FILE. 
@2 1-ACCT PICTURE IS X(4). 
@2 1-DEPT PICTURE IS X(4). 
@2 1-BODY PICTURE IS X(52). 
FD SORTED 
. BLOCK CONTAINS 6@ CHARACTERS 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS B-FILE. — 
®1 B-FILE. 
@2 2-ACCT PICTURE IS X(4). 
@2 2-DEPT PICTURE IS X(4). 
@2 2-BODY PICTURE IS X(52). 
SD WORKFL 
; DATA RECORD IS C-FILE. 
@1 C-FILE. 
@2 -3-ACCT PICTURE IS X(4). 
O02 3-DEPT PICTURE IS X(4). 
@2 3-BODY PICTURE IS X(52). 
FD PRFILE 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS D-FILE. 
@1 D-FILE. 
@2 4-ACCT PICTURE IS X(4). 
@2 4-DEPT PICTURE IS X(4). 
@2 4-BODY PICTURE IS X(52). 


Example D-4. Coding the SORT Program with the USING and GIVING Options 
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PROCEDURE DIVISION. 
OPENING SECTION. 
OPENER. 
OPEN OUTPUT PRFILE. 
A-SORT SECTION. 
Pl. 
SORT WORKFL ON ASCENDING KEY 3-ACCT 3-DEPT. 
USING INDATA GIVING SORTED. 

OK-PRINT SECTION. 
P2. OPEN INPUT SORTED. 
A-LOOP SECTION. 
P3. READ SORTED AT END GO TO A-1-MOVE. 

PERFORM A-MOVE. 

WRITE D-FILE. 

GO TO A-LOOP. 
A-MOVE SECTION. 
P4. MOVE B-FILE TO D-FILE. 
A-1-MOVE SECTION. 
P5. EXIT. 
ALL-DONE SECTION. 
P6. CLOSE SORTED PRFILE. 

STOP RUN. 


Example D-4. Coding the SORT Program with the USING and GIVING Options (cont.) 


Example 5 


Example D-5 shows coding of the MERGE program using the USING and GIVING 
options. In this example, the files that are directly involved in the merge process must 
not be open when the MERGE statement is encountered. This restriction is necessary 
because the USING and GIVING options perform the functions of the OPEN, READ, 
RETURN, WRITE, and CLOSE statements automatically. Although the use of the 
USING and GIVING options require a minimum amount of coding, it is not possible to 
select, add, modify, or delete records of the sort-merge file in any way. This means that 
no special processing procedures can be incorporated into a merge function when these 
options are used. 


The files TO-BE-MERGED1 and TO-BE-MERGED2 are merged into the file 
AFTER-THE-MERGE. This merged file is then listed after the merge function has been 
accomplished. The files that were merged were already in sorted order according to the 
keys defined in the MERGE statement. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. MERGEA. 


bd THIS MERGE PROGRAM EXAMPLE ILLUSTRATES 
x THE FOLLOWING MERGE OPTIONS 

= USING 

bg GIVING. 


ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. B7988. 


Example D-5. Coding MERGE Program with the USING and GIVING Options 
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OBJECT-COMPUTER. B7902. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT TO-BE-MERGED1 ASSIGN TO DISK. 
SELECT TO-BE-MERGED2 ASSIGN TO DISK. 
SELECT AFTER-THE-MERGE ASSIGN TO DISK. 
SELECT WORK-ING ASSIGN TO MERGE DISK. 
SELECT FOR-THE-PRINTER ASSIGN TO PRINTER. 
DATA DIVISION. 
FILE SECTION. 
SD WORK-ING 
; RECORD CONTAINS 6@ CHARACTERS 
; DATA RECORD IS C-FILE 
; BLOCK CONTAINS 6@ CHARACTERS. 
@1  C-FILE. 
@2 3-ACCT PICTURE IS X(4). 
@2 3-DEPT PICTURE IS X(4). 
@2 3-BODY PICTURE IS X(52). 
FD TO-BE-MERGED1 
| BLOCK CONTAINS 6@ CHARACTERS 
RECORD CONTAINS 6@ CHARACTERS 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS A-FILE1 VALUE OF TITLE IS "MGI". 
@1 A-FILE1. 
2 1-ACCT PICTURE IS X(4). 
@2 1-DEPT PICTURE IS X(4). 
@2 1-BODY PICTURE IS X(52). 
FD TO-BE-MERGED2 
BLOCK CONTAINS 6@ CHARACTERS 
RECORD CONTAINS 6@. CHARACTERS 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS A-FILE2 VALUE OF TITLE IS "MG2". 
@1 A-FILE2. 
@2 1-ACCT PICTURE IS X(4). 
Q2 1-DEPT PICTURE IS X(4). 
@2 1-BODY PICTURE IS X(52). 
FD AFTER-THE-MERGE 
BLOCK CONTAINS 6@ CHARACTERS 
RECORD CONTAINS 6@ CHARACTERS 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS B-FILE VALUE OF TITLE IS “AFTER/MERGE". 
@1 B-FILE. 
@2 2-ACCT PICTURE IS X(4). 
@2 2-DEPT PICTURE IS X(4). 
@2 2-BODY PICTURE IS X(52). 
FD FOR-THE-PRINTER 
LABEL RECORDS ARE OMITTED 
DATA RECORD IS D-FILE. 
@1 D-FILE. 
@2 4-ACCT PICTURE IS X(4). 
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G2 4-DEPT PICTURE IS X(4). 
G2 4-BODY PICTURE IS X(52). 
~ PROCEDURE DIVISION. 

OPENING SECTION. 

OPEN-PARA. 
OPEN OUTPUT FOR-THE-PRINTER. 

A-MERGE SECTION. 

P1. MERGE WORK-ING ON ASCENDING KEY 3-ACCT 3-DEPT 
USING TO-BE-MERGED1 TO-BE-MERGED2 
GIVING AFTER-THE-MERGE. 

OK-PRINT SECTION. 

P2. OPEN INPUT AFTER-THE-MERGE. 

A-LOOP SECTION. 

P3. READ AFTER-THE-MERGE AT END GO TO A~1-MOVE. 
PERFORM A-MOVE. 
WRITE D-FILE. 
GO TO A-LOOP. 

A-MOVE SECTION. 

P4. MOVE B-FILE TO D-FILE. 

A-1-MOVE SECTION. 

P5. EXIT. 

ALL-DONE SECTION. 

P6. CLOSE AFTER-THE-MERGE WITH LOCK. CLOSE FOR-THE-PRINTER. 
STOP RUN. 


Example D-5. Coding MERGE Program with the USING and GIVING Options (cont.) 


Example 6 


Example D-6 shows the use of remote files with variable record lengths. Variable length 
records for a remote file are declared by the use of the RECORD CONTAINS and 

the RECORD CONTAINS...DEPENDING ON phrases in the FD statement for the 
remote file in the source code. Run-time code is generated by the compiler to handle the 
variable length records. Other than specifying one of the RECORD CONTAINS phrases, 
you do not need to be concerned with the processing of variable-length records except as 
noted in the following examples. | 


IDENTIFICATION DIVISION. 

PROGRAM-ID. VAR1-METHOD1. 
ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. B7900. 
OBJECT-COMPUTER. B7929. 
INPUT-OUTPUT SECTION. 


FILE-CONTROL. 
SELECT = RMTE ASSIGN TO REMOTE. 
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DATA DIVISION. 


FILE SECTION. 


FD RMTE 

RECORD CONTAINS 125 TO 2@@ CHARACTERS. 
81 SHORT-RECORD PIC X(125). 
@1 LONG-RECORD PIC X(2@@). 


WORKING-STORAGE SECTION. 


®1 REMOTE-MESSAGE. 
@5 SPACING-AREA PIC X(5@) VALUE SPACES. 
'@5 MESSAGE-AREA PIC X(2@@) VALUE SPACES. 


PROCEDURE DIVISION. 


OPEN-REMOTE. 
OPEN I-0 RMTE. 
WRITE-SHORT-RECORD. 
* ONLY THE FIRST 125 CHARACTERS ARE WRITTEN TO FILE RMTE. 
MOVE "HELLO USER, PLEASE WAIT FOR MY MESSAGE." 
TO MESSAGE-AREA. 
WRITE SHORT-RECORD FROM REMOTE-MESSAGE. 
MOVE SPACES TO MESSAGE-AREA. 
WAIT 2. 
WRITE-LONG-RECORD. 
* UP TO 2@@ CHARACTERS ARE WRITTEN TO REMOTE FILE RMTE. 
“MOVE "HELLO USER. WELCOME TO THE WORLD OF VARIABLE 
- " LENGTH REMOTE FILE RECORDS. WE ARE HAPPY YOU ARE HERE." 
TO MESSAGE-AREA. 
WRITE LONG-RECORD FROM REMOTE-MESSAGE. 
WAIT 2. 
CLOSE-FILE. 
CLOSE RMTE. 
STOP RUN. 


Example D-6. Coding Remote Files with Variable-Record Lengths (cont.) 
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Example 7 


Example D-7 shows coding of the PERFORM program with the VARYING UNTIL 
option and the use of remote files. The program creates a lunch menu and displays it on 


the screen. 


IDENTIFICATION DIVISION. 
PROGRAM-~ID. 
ENVIRONMENT DIVISION. 


VARI-METHOD1. 


CONFIGURATION SECTION. 


SOURCE-COMPUTER. 
OBJECT-COMPUTER. 


B7980. 
B798. 


INPUT-OUTPUT SECTION. 


FILE-CONTROL. 
SELECT  RMTE 


ASSIGN TO REMOTE. 
DATA DIVISION. 
FILE SECTION. 


FD RMTE 
RECORD CONTAINS 288 TO 68@ CHARACTERS. 


OCCURS-RECORD. 


61 
@5 FILLER PIC X(129). 
@5 VARIABLE-PART. 
18 FIRST-PART PIC X(8). 
18 SECOND-PART PIC X(8@) 


OCCURS 1 TO 6 TIMES DEPENDING ON Z. 


WORKING-STORAGE SECTION. 


77 2 PIC 9 COMP VALUE 1. 

@1 ENTREES. 
@5 FILLER PIC X(15) VALUE "ONION SOUP ae 
65 FILLER PIC X(65) VALUE SPACES. 
@5 FILLER PIC X(15) VALUE "FRUIT SALAD ". 
85 FILLER PIC X(65) VALUE SPACES. 
O5 FILLER PIC X(15) VALUE "HAMBURGER " 
@5 FILLER PIC X(65) VALUE SPACES. 
@5 FILLER PIC X(15) VALUE "FRENCH FRIES ". 
65 FILLER PIC X(65) VALUE SPACES. 
@5 FILLER PIC X(15) VALUE "ICED TEA ae 
@5 FILLER PIC X(65) VALUE SPACES. 
85 FILLER PIC X(15) VALUE "ICE CREAM ie 
@5 FILLER PIC X(65) VALUE SPACES. 


@1 ENTREE-TABLE REDEFINES ENTREES. 
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@5 ENTREE PIC X(8@) OCCURS 6 TIMES. 


PROCEDURE DIVISION. 

OPEN-REMOTE. 
OPEN I-O RMTE. 
MOVE SPACES TO OCCURS-RECORD. 
MOVE " LUNCH MENU: "TO FIRST-PART. 
PERFORM WRITE-REMOTE VARYING Z FROM 1 BY 1 UNTIL Z > 6. 
CLOSE RMTE. 
STOP RUN. 

WRITE-REMOTE. 
MOVE ENTREE(Z) TO SECOND-PART(Z). 
WRITE OCCURS-RECORD. 

END-OF-JOB. 


Example D-7. Coding PERFORM Program with the VARYING UNTIL Option (cont.) . 


Example 8 
Example D-8 shows coding of a remote file. 


IDENTIFICATION DIVISION. 
PROGRAM-ID. VARI-METHOD2. 


ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. B79. 
OBJECT-COMPUTER. B7908. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT RMTE ASSIGN TO REMOTE. 


DATA DIVISION. 
FILE SECTION. 
FD RMTE 
RECORD CONTAINS 248 CHARACTERS. 
@1 RMTE-RECORD. 
@5 ACTUAL-RECORD-AREA PIC X(24@). 


WORKING-STORAGE SECTION. 
@1 MESSAGE-IN. 


@5 MESSAGE-ENTERED PIC X(14) VALUE "YOU ENTERED: 
: @5 MESSAGE-AREA PIC X(226) VALUE SPACES. 
@1 MESSAGE-OUT. 
@5 GOOD-MORNING PIC X(14) 
VALUE "GOOD MORNING ".— 
: 5 USER-NAME PIC X(17). 
@5 INSTRUCT PIC X(269) 


VALUE " CLEAR HOME AND ENTER ANY MESSAGE. THEN XMIT.". 
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PROCEDURE DIVISION. 
OPEN-REMOTE. 
OPEN I-0 RMTE. 
READ-AND-WRITE. 
THE USER IS PROMPTED TO ENTER A MESSAGE. THE MESSAGE 
ENTERED WILL BE DISPLAYED BACK ON THE TERMINAL (THE MESSAGE 
SHOULD NOT BE MORE THAN 289 CHARACTERS LONG), AND THE 
PROGRAM WILL END. 
MOVE ATTRIBUTE USERCODE OF MYSELF TO USER-NAME. 
MOVE MESSAGE-OUT TO ACTUAL-RECORD-AREA. 
WRITE RMTE-RECORD. 
READ RMTE AT END GO TO CLOSE-FILE. 
MOVE ACTUAL-RECORD-AREA TO MESSAGE-AREA. 
MOVE MESSAGE-IN TO ACTUAL-RECORD-AREA. 
WRITE RMTE-RECORD. 
CLOSE-FILE. 
CLOSE RMTE. 
STOP RUN. 


+ + 


Example D-8. Coding Remote Files (cont.) 
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In this glossary, definitions taken from outside sources are preceded by an abbreviation enclosed 
in parentheses. Definitions from Dictionary of Computing are preceded by DOC. Definitions from 
American National Dictionary for Information Processing Systems are preceded by ANDIPS. 


A 


abbreviated combined relation condition 
The combined condition that results from the explicit omission of a common subject or a 
common relational operator in a sequence of relation conditions. 


access mode 
The manner in which records are to be operated on within a file. The two possible access 
modes are random and sequential. 


actual decimal point 
The physical representation of the decimal point position in a data item, using either of 
the decimal point characters: the period (.) or the comma (,). 


actual key | . 
A key whose contents identify a logical record in a sequential file. 


ADDS 
See Advanced Data Dictionary System. 


Advanced Data Dictionary System (ADDS) 
A software product that allows for the centralized definition, storage, and retrieval of 
data descriptions. 


ALGOL 
Algorithmic language. A structured, high-level programming language that provides 
the basis for the stack architecture of the Unisys A Series systems. ALGOL was the 
first block-structured language developed in the 1960s and served as a basis for such 
languages as Pascal and Ada. It is still used extensively on A Series systems, primarily 
for systems programming. 
alphabet-name 

A user-defined word, in the SPECIAL-NAMES paragraph of the ENVIRONMENT 
DIVISION of a program, that assigns a name to a specific character set or collating 
sequence, or both. 


alphabetic character — 
A character that belongs to the following set of letters in either uppercase or lowercase: 
A, B, C, D, E, FE G, H, 1, J, K, L, M; N, O, B Q, R, S, T, U, V, W, X, Y, Z, and the space 
(blank). . | 


alphanumeric character 
Any character in the computer’s character set. 
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alternate record key . 
A key, other than a prime record key, whose contents identify a record of an indexed file. 


arithmetic expression 
An expression containing any of the following: a numeric variable, a numeric elementary 
item, a numeric literal, identifiers and literals separated by arithmetic operators, two 
arithmetic expressions separated by an arithmetic operator, or an arithmetic expression 
enclosed in parentheses. 


arithmetic operator . 
(1) (DOC) An operator that specifies an operation with numeric inputs and outputs; 
for example, ADD, SUBTRACT, or DIVIDE. (2) A single character or a fixed 
2-character combination belonging to the following set: + (addition), — (subtraction), 
* (multiplication), / (division), or ** (exponentiation). 


ascending key 
A key that has values on which data are ordered, starting with the lowest value of the 
key up to the highest value of the key, in accordance with the rules for comparing data 
items. 


ASCII 
American Standard Code for Information Interchange. A standard 7-bit or 8-bit 
information code used to represent alphanumeric characters, control characters, and 
graphic characters on a computer system. 


assumed decimal point 
A decimal point position that does not require the existence of an actual character 
in a data item. The assumed decimal point has logical canine but no physical 
representation. 


At End condition . 
A condition caused during one of the following: the execution of a READ statement for a 
sequentially accessed file when no next logical record exists; the execution of a RETURN 
statement when no next logical record exists for the associated sort or merge files; or 
the execution of a SEARCH statement when the search operation terminates without 
satisfying the condition specified in any of the associated WHEN phrases. 


binding 
The process of combining one or more separately compiled subprogram object code files 
with a host object code file to produce a single object code file. This process is performed 
by the Binder program. 

block 


(1) A group of physically adjacent records that can be transferred to or from a physical 
device as a group. (2) A program, or a part of a program, that is treated by the processor 
as a discrete unit. Examples are a procedure in ALGOL, a procedure or function in 
Pascal, a subroutine or function in FORTRAN, or a complete COBOL program. 
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body group . 
In COBOL74, the generic name for a report group of type DETAIL, CONTROL 
HEADING, or CONTROL FOOTING. 


C 


called program 
A program that is the object of a CALL statement and is combined at object time with 
the calling program to produce a run unit. 


calling program 
A program that executes a CALL statement to another program. 


CANDE 
See Command and Edit. 


CCR 


See compiler control record. 


CD-name 
A user-defined word that names a message control system (MCS) interface area. 


character 
The actual or coded representation of a digit, letter, or special symbol in display form. 


character position 
The amount of physical storage required to store a single standard data format character 
whose usage is described as DISPLAY. Further characteristics of the physical storage are 
defined by the implementor. 


character set 
(ANDIPS) A finite set of different characters upon which agreement has been 
reached and that is considered complete for some purpose. For example, in COBOL 
programming, the character set contains 52 specific characters. 


class condition | 
The proposition, for which a truth value can be determined, that the content of an item 
is wholly alphabetic or wholly numeric. 


clause 
An ordered set of consecutive character strings that specifies an attribute of an entry. 


COBOL . 
. Common Business-Oriented Language. A widely used, procedure-oriented language 
intended for use in solving problems in business data processing. The main 
characteristics of COBOL are the easy readability of programs and a considerable degree 
of machine independence. COBOL is the most widely used procedure-oriented language. 


COBOL74 


A version of the COBOL language that is compatible with the ANSI X3.23-1974 
standard. 
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collating sequence 
(DOC) A set of rules establishing the order in which items will be aetandeds in a set. 
Common collating sequences are “alphabetic order” and “numerical order” with, often, 
additional rules for dealing with symbols, punctuation, and spaces. 


column é 
A character position in a print line. The column numbers are incremented by 1, starting 
from 1 at the leftmost character position of the print line and extending to the rightmost 
position of the print line. 


combined condition 
A condition that results from connecting two or more conditions with the AND or the OR 
logical operator. 


Command and Edit (CANDE) 
A time-sharing message control system (MCS) that enables a user to create and edit 
files, and to develop, test, and execute programs, interactively. 


comment line 
A line in a source program used only for Aocamantation purposes. 


comment-entry 
An entry in the IDENTIFICATION DIVISION that can be any combination of 
characters from the computer character set. 


communication description entry 
An entry that is composed of the level-indicator communication description (CD), a 
CD-name, and a set of clauses as required. The communication description entry 
describes the interface between the message control system (MCS) and the program. 


communication device ; 
A mechanism (hardware, or hardware and software) capable of sending data to a queue 
and/or receiving data from a queue. This mechanism can be a computer or a peripheral 
device. One or more programs containing communication description (CD) entries and 
residing within the same computer define one or more of these mechanisms. 


COMMUNICATION SECTION 
The section of the DATA DIVISION that describes the interface areas between 
the message control system (MCS) and the program, composed of one or more 
communication open entries. 


Communications Management System (COMS) 
A general message control system (MCS) that controls online environments on A Series 
systems. COMS can support the processing of multiprogram transactions, single-station 
remote files, and multistation remote files. . 


compile time 


The time during which a compiler analyzes program text and generates an object code 
file. 


Glossary—4 . 8600 0296-000 


Glossary 


compiler . ! 
A computer program that translates instructions written in a source language, such as 
COBOL or ALGOL, into machine-executable object code. 


compiler control record (CCR) 
A record in a source program that begins with a dollar sign ($) and contains one or 
more options that control various compiler functions. These specifications can appear 
anywhere in the source program unless otherwise specified. 


compiler-directing statement 
A statement beginning with a compiler-directing verb that causes the compiler to take a 
specific action during compilation. 


complex condition 
A combination of two or more simple conditions, combined conditions, or other complex 
conditions with logical connectors. 


computer-name 
A system-name that identifies the computer on which the progreuty is to be compiled or 
run. 


COMS 
See Communications Management System. 


condition 
A status for which a truth value can be determined at execution time. The term 
condition (condition-1, condition-2, and so forth) implies a conditional expression 
consisting of either a simple condition optionally enclosed in parentheses or a combined 
condition consisting of a combination of simple conditions, logical operators, and 
parentheses, for which a truth value can be determined. 


condition-name 
A user-defined word assigned to a specific value or range of values within the complete 
set of values that a conditional variable can have. A condition-name can also be a 
user-defined word assigned to a status of a switch or device. 


condition-name condition 
The proposition, for which a truth value can be determined, that the valde of 
a conditional variable is equal to one of the values attributed to an associated 
condition-name. 


conditional expression 
A simple or complex condition specified in an IF, PERFORM, or SEARCH statement. 


conditional statement 
(1) A structured statement including a Boolean condition (explicit or implied) that 
determines whether a subcomponent statement is to be executed. (2) A statement 
specifying that the truth value of a condition is to be determined and that the 
subsequent action of the object program depends on this truth value. © 


conditional variable 
A data item for which at least one value has a condition-name assigned to it. 
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CONFIGURATION SECTION 
A section of the ENVIRONMENT DIVISION that describes overall specifications of the 
source and object computers. 


connective 
A reserved word used to do one of the following: associate a data-name, 
paragraph-name, condition-name, or text-name with its qualifier; link two or more 
consecutive operands; or form conditions. 


contiguous items 
Items that are described by consecutive entries in the DATA DIVISION and that have a 
hierarchical relationship to each other. 


control break 
A change in the value of a data item that is used to control the hierarchical structure of a 
report. 


control break level 
The relative position within a control hierarchy at which the most major control break 
occurred. 


control data-name 
A data-name that appears in a CONTROL clause and refers to a control data item. 


CONTROL FOOTING 
A report group presented at the end of the control group of which it is a member. 


control group . . 
A set of body groups presented for a given value of a control data item or of FINAL. 
Each control group can begin with a CONTROL HEADING, end with a CONTROL 
FOOTING, and contain DETAIL report groups. 


CONTROL HEADING 
A report group presented at the beginning of the control group of which it is a member. 


control hierarchy . 
A designated sequence of report subdivisions defined by the positional order of FINAL 
and the data-names within a CONTROL clause. 


counter 
A data item used for storing numbers or number representations in a manner that 
permits these numbers to be increased or decreased by the value of another number, or 
to be set to 0 or to an arbitrary positive or negative value. 


CP 2000 
_ See CP 2000 communications processor. 


CP 2000 communications processor 
A data communications processor (DCP) that provides communications interfaces to local 
area networks (LANs) and wide area networks (WANs), including BNA Version 2 and 
Transmission Control Protocol/Internet Protocol (TCP/IP) networks. The CP 2000 also 
provides connections to terminals controlled by BNA Version 2 software. . 
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currency sign 
In the COBOL character set, the character $. 


currency symbol 
The character defined by the CURRENCY SIGN clause in the SPECIAL-NAMES 
paragraph. If no CURRENCY SIGN clause is present, the currency symbol is identical to 
the currency sign (§). 


current record 
The record that is available in the record area associated with a file. 


current record pointer 
A conceptual entity used to select the next record. 


D 


data clause 
A clause that appears in a data-description entry in the DATA DIVISION and Reeves 
information describing a particular attribute of a data item. 


data communications interface (DCD library 
A library that serves as the direct programmatic interface to the Communications 
Management System (COMS). Application programs must communicate with COMS 
through the DCI library to use agendas, processing items, routing by trancode, and 
synchronized recovery. 


data item 
In COBOL, a character or a set of contiguous characters (excluding, in either case, 
literals) defined as a unit of data by the COBOL program. 


Data Management System It (DMSID) 
A specialized system software package used to describe a database and maintain the 
relationships among the data elements in the database. 


data-description entry 
An entry in the DATA DIVISION that is composed of a level-number followed by a 
data-name, if required, and a set of data clauses, as required. 


data-name 
A user-defined word that identifies a data item described in a data-description entry in 
the DATA DIVISION. When used in the general formats, a data-name represents a word 
that cannot be subscripted, indexed, or qualified unless specifically permitted by the 
rules for that format. 


DCI library 
See data communications interface (DCD) library. 


debugging line 
Any line with a D in the indicator area of the line. 
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debugging section 
A section that contains a USE FOR DEBUGGING statement. 


declarative-sentence 
A compiler-directing sentence consisting of a single USE statement terminated by the 
separator period. 


DECLARATIVES 
A set of one or more special-purpose sections, written at the beginning of 
the PROCEDURE DIVISION, the first of which is preceded by the keyword 
DECLARATIVES and the last of which is followed by the keywords END 
DECLARATIVES. A declarative is composed of a section header, followed by a USE 
compiler-directing sentence, followed by zero or more associated paragraphs. 


delimiter 
A character or sequence of contiguous characters that identifies the end of a string 
of characters and separates that string of characters from the following string of 
characters. . 


descending key 
A key that has values on which data are ordered, starting with the highest value of the 
key down to the lowest value of the key, in accordance.with the rules for comparing data 
items. 


destination 
The symbolic identification of the receiver of a transmission from a queue. 


digit portion . 9 | . 
The low order, or least significant, 4 bits in a byte. Contrast with zone portion. 


digit position 
The amount of physical storage required to store a single digit. This amount can 
vary depending on the usage of the data item describing the digit position. Further 
characteristics of the physical storage are defined by the implementor. | 


distributed systems service (DSS) ; 
One of a collection of services provided on Unisys hosts to support communications 
across multihost networks. DSSs can be services such as file handling, station transfer, 
and mail transfer. 


division 
A set of zero or more sections of paragraphs, called the division body, that is formed and 
combined according to established rules. The four divisions ina COBOL program are the 
IDENTIFICATION DIVISION, ENVIRONMENT DIVISION, DATA DIVISION, and 
PROCEDURE DIVISION. 


division header 
A combination of words followed by a period and a space indicating the beginning of a 
division. The division headers are IDENTIFICATION DIVISION, ENVIRONMENT 
DIVISION, DATA DIVISION, and PROCEDURE DIVISION. 
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DMSII 
See Data Management System II. 


DSS 
See distributed systems service. 


dynamic access 
An access mode in which specific logical records can be obtained from or placed into a 
mass storage file in a nonsequential manner and obtained from a file in a sequential 
manner during the scope of the same OPEN statement. 


E 


EBCDIC 
Extended Binary Coded Decimal Interchange Code. An 8-bit code representing 256 
graphic and control characters that are the native character set of most mainframe 
systems. 


editing character 
A character used to edit numeric fields. 


Editor 
. A Unisys utility program designed to create and modify program source and data files. 
EDO 
See end-of-double-octet character. 
EGI 


See end-of-group indicator. 


elementary item . 
A data item described as not being further logically subdivided. 


EMI 
See end-of-message indicator. 


end of PROCEDURE DIVISION . 
The physical position in a source program after which no further procedures appear. 


end of task (EOT) _ 
The termination of processing of a task. 


end-of-double-octet (EDO) character 
A character that signals the end of a double-octet character string. 


end-of-group indicator (EGD 
An option indicator that specifies the end of a group of data in a data communications 
message. | 


end-of-message indicator (EMI) 
An option indicator that specifies the end of a data communications message. . 
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end-of-segment indicator (ESD 
(1) In data communications, an option indicator that specifies the end of a segment of 
data in a message. (2) In COBOL74, an option indicator in the SEND statement that 
specifies the end of a segment of data in a message to be sent. 


entry 
In a source program, any descriptive set of consecutive clauses terminated by a period 
and written in the IDENTIFICATION DIVISION, ENVIRONMENT DIVISION, or 
DATA DIVISION. 

entry point 


A procedure or function that is a library object. 


environment clause 
A clause that appears as part of an ENVIRONMENT DIVISION entry. 


EOT 
See end of task. 


ESI 
See end-of-segment indicator. 


event-identifier 
An event variable, event-valued file attribute, or Bue: valued task attribute. 


event-identifier condition . 
An event-identifier used as a condition to return the value TRUE if the event has been 
caused and not reset, and to return the value FALSE if the event is reset. 


execution time | 
The time during which an object code file is executed. Synonym for run time and, in 
COBOL, object time. 


extend mode 
In COBOL74, the state of a file after execution of an OPEN statement with the 
EXTEND phrase specified for that file, and before the execution of a CLOSE statement 
for that file. 


F 


family substitution 
A method for redirecting references to files on a disk family to avoid entering the 
actual family name in commands or file-names. For example, if a user enters FAMILY 
DISK= PACK OTHERWISE DISK, that user’s file requests are checkes on disk packs 
named PACK and DISK. 


FD 
See File Description (FD) entry. 


figurative constant 
_ Acompiler-generated value referenced by using certain reserved words. 
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file 
A named group of related records. See logical file, physical file. 


file clause 
A clause that appears as part of any of the following DATA DIVISION entries: file 
description (FD), sort merge description (SD), and communication description (CD). 


File Description (FD) entry 
An entry in the FILE SECTION of the DATA DIVISION that is composed of the 
level-indicator FD, a file-name, and a set of file clauses as required. 


file name 
A user-defined word that names a file described in a file description entry or a 
sort-merge description entry within the FILE SECTION of the DATA DIVISION. 


file organization 
The permanent logical file structure established when a file is created. 


FILE SECTION 
The section of the DATA DIVISION that contains file description entries and sort-merge 
file description (SD) entries with their associated record descriptions. 


FILE-CONTROL 
The name of an ENVIRONMENT DIVISION paragraph in which the data files for a 
given source program are declared. 


floating-point literal . 
The value of a literal shown with the decimal part of a number multiplied by the power of _ 
10 and used as an alternative for a standard numeric literal. 


format 
(1) The organization of an array of storage points in memory. Formats, and other 
memory structures, make it possible for the Master Control Program (MCP) to identify 
and move areas of memory. (2) The specific arrangement of a set of data. 

FORTRAN 


Formula Translation. A high-level, structured programming language intended primarily 
for scientific use. 


G 


group item 
In Data Management System IT (DMSI)), a collection of data items that can be viewed as 
a single data item. 


H 


hexadecimal literal 
A character string bounded by at signs (@). The string of characters must consist of one 
or more characters chosen from the set of hexadecimal characters. 
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high-order end 
The leftmost character of a character string. 


I-O mode 
The state of a file after execution of an open operation, whether implicit or explicit, with 
the I-O phrase specified. The file remains in nI- O mode until the execution of a close 
operation for that file. 


I-O-CONTROL 
The name of an ENVIRONMENT DIVISION paragraph in which the jabieiag are 
specified: object program requirements for specific I/O techniques, rerun points, sharing 
of same areas by several data files, and multiple file storage on a single I/O device. 


Vo 
Input/output. An operation in which the system reads data from or writes data to a file 
on a peripheral device such as a disk drive. 


identifier (ID) " 
A data-name followed by the required combination of qualifiers, subscripts, and indexes 
necessary to make unique reference to a data item. 


imperative statement | 
A statement that begins with an imperative verb and specifies an unconditional action to 
be taken. An imperative statement can consist of a sequence of imperative statements. 


implementor-name 
A system-name that refers to a particular feature available on the computing system of 
that implementor. 


index 
(1) A value used to specify a particular element of an array variable. (2) A computer 
storage location, the contents of which identify a particular element in a table. 


index data item 
A data item in which the value associated with an index-name can be stored i in a form 
specified by the implementor. 


index-name 
A user-defined word that identifies an index associated with a specific table. 


indexed data-name 
_ An identifier composed of a data-name followed by one or more index-names enclosed in 
parentheses. 


indexed file . 

A file whose records are accessed by a key, which is a field in each record. An entry 
containing the key value and physical address of each record is stored in an index 
associated with the file. The index entries are ordered by key value. Access to an 
indexed file is either sequential or random. 
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indexed organization 
The permanent, logical file structure in which each record is identified by the value of 
one or more keys within that record. 


input file 
A file opened in the input mode. 


input mode 
The state of a file after execution of an OPEN statement with the INPUT phrase 
specified for that file. The file remains in input mode until the execution of a CLOSE 
statement for that file. 


input procedure 
In sorting, a group of statements executed before each record is released to be sorted. 


Input-Output file 
A file opened in the I-O mode. 


INPUT-OUTPUT SECTION 
The section of the ENVIRONMENT DIVISION that names the files and the external 
media required by an object program, and that provides information required for 
transmission and handling of data during execution of the object program. 


integer - 
A numeric literal or a numeric data item that does not include any character positions to 
the right of the assumed decimal point. 


Inter-Program Communication (IPC) 
In COBOL74, a module that allows a program to communicate with one or more 
programs in order to share date items and transfer control within a run unit. 


intermediate data item 
A signed numeric data item provided by the implementor that contains the results 
developed in the course of an arithmetic operation before the final result is moved to the 
resultant identifier, if any. 


INVALID KEY condition 
A condition, at object time, caused when a specific value of the key associated with an 
indexed or relative file is determined to be invalid. 


IPC 
_ See Inter-Program Communication. 


K 


Kanji 
The standard Japanese character set for information exchange. Each Kanji character is 
2 bytes (16 bits) in length and takes two positions on a form image. 
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Kanji character literal 
_ Acharacter string bounded on the left by the separator NC" and on the right bya 
quotation mark ("). The string contains Kanji characters between the beginning and 
ending quotation marks. 


key 
A data item that identifies the location of a record, or a group of data items that 
identifies the ordering of data. 


key of reference 
The prime or alternate key currently being used to access records within an indexed file. . 


keyword 
A reserved word that must be present when the format in which the word appears is 
used in a source program. 


L 


LAN 


See local area network. 


language-name 
A system-name that specifies a particular programming language. 


level-indicator 
Two alphabetic characters (DB, CD, FD, LD, QD, RD, and SD) that identify a specific 
type of file or a position in a hierarchy. 


level-number 
A user-defined word that indicates the position of a data item in the hierarchical 
structure of a logical record or that indicates special properties of a data-description 
entry. A level-number is expressed as a 1- or 2-digit number. 


library object 
An object that is shared by a library and one or more user programs. 


library text 
A sequence of character strings, a sequence of separators, or a sequence of both 
character strings and separators in a library. 


library-name 
A user-defined word that identifies a library that is to be used by the compiler for 2 a given 
source program compilation. 


line 
(1) A row of text in a printout. (2) A data transmission link between two computers or 
between a computer and its associated terminals. 


line number 
An integer that denotes the vertical position of a report line on a page. 
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LINKAGE SECTION | 
The section in the DATA DIVISION of a called program that describes data items 
available from the calling program. Both the calling and the called program can refer to 
these data items. 


literal 
A character string whose value is implied by the ordered set of characters that compose 
the string. 


local area network (LAN) 
A network that enables high-speed communications among various devices within a 
relatively small area. 


logical file 
A file variable declared in a program, which represents the file and its structure to the 
program. A logical file has no properties of its own. until it is described by file attributes 
or associated with a physical file. 


logical operator 
An operator that corresponds to the logical (Boolean) operation of AND, OR, or NOT. 


logical record 
The most inclusive data item. The level-number for a logical record is 01. 


low-order end 
The rightmost character of a character string. 


M 


mass storage 
A storage medium on which data can be organized and maintained in both a sequential 
and nonsequential manner. 


mass storage file 
A collection of records assigned to a mass storage medium. 


master control program (MCP) 
The central program of the A Series operating system. The term applies to any master 
control program that Unisys may release for A Series systems. 


MCP 
See master control program. 


MCS 
See message control system. 


merge file 
A collection of records to be merged. 


message ; 
_ Data associated with an end-of-message indicator or an end-of-group indicator. 
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message control system (MCS) 
A program that controls the flow of messages between terminals, application programs, 
and the operating system. MCS functions can include message routing, access control, 
audit and recovery, system management, and message formatting. 


message count 
The number of complete messages in the designated message queue. 


message indicator 
An indicator that notifies the message control system (MCS) that a ore condition 
exists. The indicators are end-of-group indicator (EGI), end-of-message indicator (EMI), 
and end-of-segment indicator (ESI). An EGI is conceptually equivalent to an ESI, EMI, 
and EGI. An EMI is conceptually equivalent to an ESI and EMI. Thus, a segment can be 
terminated by an ESI, EMI, or EGI, and a message can be terminated by an EMI or EGI. 


message segment 
A subdivision of a message. A segment is normally associated with an end-of-segment 
indicator. 


mnemonic-name 
A user-defined word that is associated in the ENVIRONMENT DIVISION with a 
specified implementor-name. 


N 


native character set 
The implementor-defined character set associated with the computer for which object 
code is generated. 


native collating sequence | 
The implementor-defined collating sequence associated with the native character set. 


negated combined condition 
A condition that results from a NOT logical eae immediately followed by a combined 
condition enclosed in parentheses. 


negated simple condition 
. A condition that results from a NOT logical operator immediately followed by a simple 
condition. 


next executable sentence 
The sentence to which control is tecusiorned after execution of the current statement is 
complete. 


next executable statement 
The statement to which control is transferred after execution of the current statement is 
complete. 


next record 
The record that logically follows the current record of a file. 
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noncontiguous items 
Elementary data items in the WORKING-STORAGE and LINKAGE SECTIONs that 
have no hierarchical relationship to other data items. 


nonnumeric item 
A data item whose contents can be composed of any combination of characters taken 
from the character set of the computer. Certain categories of nonnumeric items can be 
formed from more restricted character sets. 


nonnumeric literal 
A character string bounded by quotation marks ("). The string can include any character 
in the character set of the computer. To represent a single quotation mark character 
within a nonnumeric literal, two contiguous quotation marks must be used. 


numeric character 
A character in the set of digits 0 through 9. 


numeric item 
In Data Management System II (DMSII), a data item whose description restricts its 
contents to a value represented by numeric characters. 


numeric literal 
A literal composed of one or more numeric characters that can also contain either a 
decimal point, an algebraic sign, or both. The decimal point must not be the rightmost 
character. The algebraic sign, if present, must be the leftmost character. 


0 . 


object code file | 
A file produced by a compiler when a program is compiled successfully. The file contains 
instructions in machine-executable object code. 


object of entry 
In a DATA DIVISION entry in COBOL, a set of operands and reserved words that 
immediately follows the subject of the entry. 


object program 
A set or group of executable machine-language instructions and other material designed 
to interact with data to provide problem solutions. An object program is generally the 
machine-language result of the operation of a high-level language a on a source 
program. See also object code file, compiler. 


object time 
The time during which an object program is executed. Synonym for run time, execution 
time. 


OBJECT-COMPUTER 


A paragraph in the ENVIRONMENT DIVISION that describes the computer 
environment in which the object program is to be executed. 
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ODT 
See operator display terminal. 


open mode 
The state of a file after execution of an OPEN statement for that file and before the 
execution of a CLOSE statement for that file. The particular open mode is specified i in 
the OPEN statement with either an INPUT, OUTPUT, I-O, or EXTEND phrase. 


operand 
Any lowercase word that appears in a statement or entry format. 


operational sign 
An algebraic sign, associated with a numeric data item or a numeric literal, that indicates 
whether the value is positive or negative. 


operator display terminal (ODT) 
A terminal or other device that is connected to the eee in such a way that it can 
communicate directly with the operating system. The ODT allows operations personnel 
to accomplish system operations functions through either of two operating modes: 
system command mode or datacomm mode. 


optional word 
A reserved word included in a programming language to improve the readability of a 
source statement. The user can include or omit an optional word. 


ordering sequence value (OSV) 
An integer value between 1 and 255 that is assigned to each code position in a coded 
character set and represents a relative ordering value. An ordering value of 0 signifies 
the lowest ranking in the coded character set and an ordering value that is greater than 
all other ordering values signifies the highest ranking. More than one code position can 
be assigned the same omens value. 


OSV 
See ordering sequence value. 


output file » 
A file opened in athe: output mode or extend mode. 


output mode 
The state of a file after execution of an OPEN statement, with the OUTPUT or 
EXTEND phrase specified for that file. The file remains in output mode until execution 
of a CLOSE statement for that file. 


output procedure 
A set of statements to which control is given during execution of a SORT statement after 
the sort function is completed, or during execution of a MERGE statement after the 
merge function has selected the next record in merged order. 
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Pp 


page 
A vertical division of a report representing a physical separation of report data. The 
separation is based on internal reporting requirements and/or external characteristics of 
the reporting medium. 


page body 
That part of the logical page in which lines can be written and ace 


page footing 
A report group presented at the end of a report page as determined by the Report 
Writer Control System (RWCS). 


page heading 
. Areport group presented at the beginning of a report page as determined by the Report 
Writer Control System (RWCS). 


paragraph 

An identifiable group of entries (in the IDENTIFICATION DIVISION and the 
ENVIRONMENT DIVISION) or sentences (in the PROCEDURE DIVISION). A 
paragraph in the IDENTIFICATION DIVISION and the ENVIRONMENT DIVISION 
is identified by a paragraph header. A paragraph in the PROCEDURE DIVISION is 
identified by a paragraph-name. 


paragraph header 
A reserved word followed by a period and a space that indicates the beginning of a 
paragraph in the IDENTIFICATION DIVISION and the ENVIRONMENT DIVISION. 


paragraph-name 
A user-defined word that identifies and begins a paragraph in the PROCEDURE 


DIVISION. 

phrase . 
An ordered set of one or more consecutive COBOL character strings that forms a portion 
of a COBOL procedural statement or of a COBOL clause. 

physical file 


A file as it is stored on a particular recording aediini such as a disk or a tape. 


physical record 
A physical unit of data that is normally composed of one or more logical records. A 
. physical record is also called a block. For mass storage files, a block can contain a portion 
of a logical record. The size of a block has no direct relationship to the size of the file 
within which the block is contained or to the size of the logical record or records that are 
either continued within the block or that overlap the block. See also block. 


port file 


A type of file, composed of one or more subfiles, for which I/O operations occur between 
two processes rather than between a logical file and a physical device. 
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prime record key 
A key with contents that identify a record in an indexed file. 


printable group 
A report group that contains at least one print line. 


printable item . 
A data item, the extent and contents of which are specified by an elementary report 
entry. This elementary report entry contains a COLUMN NUMBER clause, a PICTURE 
clause, and a SOURCE, SUM, or VALUE clause. 


priority sequence value (PSV) 
An integer value between 1 and 15 that is assigned to each code position in a coded 
character set and represents a relative priority within an ordering sequence value 
(OSV). Each code position that has a unique ordering value is assigned a priority value of 
1. For code positions with the same OSV, a priority value of 1 signifies the lowest ranking 
in the OSV, and a priority value which is greater than all other priority values signifies 
the highest ranking. 


procedure 
A paragraph or group of logically successive paragraphs, or a section or group of logically 
successive sections, within the PROCEDURE DIVISION. 


procedure-name . 
A user-defined word that names a paragraph or section in the PROCEDURE DIVISION. 
The procedure-name consists of a paragraph-name (which can be qualified) or a 
section-name. 


program-name 
A user-defined word that identifies a COBOL source program. 


pseudotext . 
A sequence of text-words or comments in a source program or COBOL library bounded 
by, but not including, pseudotext delimiters. 


pseudotext delimiter 
Two contiguous equal sign (=) characters used to delimit pseudotext. 


PSV 


See priority sequence value. 


punctuation character 
A character that separates and organizes the elements of a command or input statement. 
These characters are usually characters that are neither alphabetic nor numeric. Each 
programming language and software product has its own conventions for interpreting 
punctuation characters. 
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Q 


qualified data-name 
An identifier composed of a data-name followed by one or more sets of either of the 
connectives OF or IN followed by a data-name qualifier. 


qualifier 
Any of the following items: a data-name used in a reference together with another 
data-name at a lower level in the same hierarchy; a section-name used in a reference 
together with a paragraph-name specified in that section; or a library-name used in a 
reference together with a text-name associated with that library. 


queue 
A data structure used for BeNorMig objects; the objects are removed in the same order they 
are stored. 


queue name 
A symbolic name that indicates to the message control system (MCS) the logical path by 
which a message or a portion of a completed message is accessible in a queue. 


R 


random access 
An access dechuiigiie that permits the storage and retrieval of a single data element 
without reference to other preceding data elements. If the data is stored in files, the 
technique permits a single record of a file to be accessed by specifying one or more keys 
associated with that record, without first having to access all the records that precede 
the record. Contrast with sequential access. 


record 
(1) A group of logically related items of data in a file that are treated as a unit. (2) The 
data read from or written to a file in one execution of a read or write statement ina 
program. 


record area 
A storage area allocated for the purpose of processing the record described i na 
record-description entry in the FILE SECTION. 


record dedeviption 
See record-description entry. 


record key 
A key, either the prime record key 07 or an alternate record key, with contents that identify 
a record within an indexed file. 


record-description entry 
The total set of data-description entries associated with a particular record. 


record-name 


A user-defined word that names a record described in a record-description entry in the 
DATA DIVISION. 
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reference format 
A format that provides a standard method for describing COBOL source programs. 


relation 
See relational operator. 


relation condition 
A proposition, for which a truth value can be determined, in which the value of an 
arithmetic expression or data item has a specific relationship to the value of another 
arithmetic expression or data item. 


relational character 
A character that signifies a relationship between the values of two epebaniae: The 
ange relational characters are the pOHOWANE symbols: > (greater than), < (less than), 
= (equal to). 


relational operator 
A reserved word, a relational character, a group of consecutive reserved weerds, ora 
group of consecutive reserved words and relational characters used in the construction of 
a relation condition. 


relative file ae 
In an indexed file management system, a file with relative organization. 


relative key 
In an indexed file management system, a key with contents that identify a logical record 
in a relative file. 


relative organization 
In an indexed file management sien. the permanent, logical file structure in 1 which 
each record is uniquely identified by an integer value greater than zero that specifies the 
logical ordinal position of the record in the file. 


report clause 
A clause in the REPORT SECTION of the DATA DIVISION that appears in a 
report-description entry or a report-group description entry. 


report file 
An output file with a description entry that contains a REPORT clause. The contents 
of a report file consist of records that are written under control of the Report Writer 
Control System (RWCS). 


report footing | 
_ Areport group that is presented only at the end of a a 


report group 
An 01-level-number entry and its subordinate entries i in the REPORT SECTION of the 
DATA DIVISION. 


report heading 
A report group that is presented only at the eee of a ceport: 
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report line 
A division of a page representing one row of horizontal character positions. Each 
character position of a report line is aligned vertically beneath the corresponding 
character position of the report line above it. Report lines are incremented by 1, starting 
with the number 1 at the top of the page. 


REPORT SECTION 
The section of the DATA DIVISION that contains one or more report-description entries 
and their associated report-group description entries. 


Report Writer Control System (RWCS) 
An object-time (run-time) control system, provided by the enplementar that constructs 
reports. 


Report Writer logical record 
A record that consists of the COBOL Report Writer Control System (RWCS) print line 
and associated control information necessary for selection and vertical positioning of the 
‘record. 


report-description entry 
An entry in the REPORT SECTION of the DATA DIVISION that is composed of the 
level-indicator RD, the report name, and a set of report clauses. 


report-group description entry 
An entry in the REPORT SECTION of the DATA DIVISION et is composed of the 
level-number 01, the optional data-name, a TYPE clause, and an optional set of report 
clauses. 


report-name 
A user-defined word that names a report described in a report-description entry within 
the REPORT SECTION of the DATA DIVISION. 


reserved word 
A word that has special meaning within a programming language and that generally 
cannot be redefined or redeclared by the programmer. 


resultant identifier 
A user-defined data item that contains the result of an abehintie expression. 


routine-name 
A user-defined word that identifies a procedure written in a language other than 
COBOL. 7 


run time 
The time during which an object code file or user interface system (UIS) is executed. 
Synonym for execution time and, in COBOL, object time. 


run unit 


A set of one or more object programs that functions, at object time, as a unit to provide 
problem solutions. 
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RWCS 
See Report Writer Control System. 


S 


Screen Design Facility (SDF) 
The InterPro product used for creating forms for online, transaction-based application 
systems. 


Screen Design Facility Plus (SDF Plus) 
A Unisys product used for creating user interface systems (UISs) for online, 
transaction-based application systems. 


SD 
See Sort-Merge File-Description (SD) entry. 

SDF 
See Screen Design Facility. 

SDF Plus 
See Screen Design Facility Plus. 

SDO 

. See start-of-double-octet character. 
section 


A set of zero or more paragraphs or entries, called a section body, the first of which is 
preceded by a enon header. Each section consists of the section header and the section 
body. 


section header 
A combination of words followed by a period and a space that indicates the beginning of 
a section in the ENVIRONMENT DIVISION, DATA DIVISION, and PROCEDURE 
DIVISION. In the ENVIRONMENT DIVISION and DATA DIVISION, a section header 
is composed of reserved words followed by a period and a space. In the PROCEDURE 
DIVISION, a section header is composed of a section-name, followed by the reserved 
word SECTION, followed by a segment-number (optional), followed by a period and a 
space. 


section-name 
A user-defined word that names a section in the PROCEDURE DIVISION. 


segment-number 
A user-defined number that classifies sections in the PROCEDURE DIVISION for 
purposes of segmentation. Segment-numbers can contain only the digits 0 through 9. A 
segment-number can be expressed as a 1-, 2-, 3-, or 4-digit number. 


Glossary-24 | 8600 0296-000 


Glossary 


Semantic Information Manager (SIM) 
The basis of the InfoHxec™ environment. SIM is a database management system used 
to describe and maintain associations among data by means of subclass-superclass 
relationships and linking attributes. . 


sentence 
A sequence of one or more statements, the last of which is terminated by a period 
followed by a space. 


separator 
A punctuation character used to delimit character strings. 


sequential access 
An access technique in which logical records are obtained from or placed into a file in a 
consecutive sequence determined by the order of the records in the file. Contrast with 
random access. 


sequential file 
A data file in which records are organized according to the order in which they are stored 
in the file. A sequential file is read consecutively. 


sequential organization 
The permanent logical file structure in which a record is identified bya 
predecessor-to-successor relationship established when the record is placed into the file. 


session: . 
The interactions between a user and a message control system (MCS) during a particular 
period of time that is assigned an identifying session number. Logging on initiates a new 
session; logging off terminates a session. Each Menu-Assisted Resource Control (MARC) 
or Command and Edit language (CANDE) aeeeus ata terminal accesses a different 

_session. 


sign condition 
The proposition that the algebraic value of a data item or an arithmetic expression is less 
than, greater than, or a to 0 (zero). A truth condition can be determined for a a Sign 
condition. 


SIM 


See Semantic Information Manager. 


simple condition 
Any single condition chosen from the following set: relation condition, class condition, 
condition-name condition, switch-status condition, sign condition, and a simple condition 
enclosed in parentheses. 


SOK . 
See start of Kanji. 


InfoExec is a trademark of Unisys Corporation. 
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sort file 
A collection of records to be sorted by a SORT statement. The sort file is created and 
can be used by the sort function only. 


Sort-Merge File-Description (SD) entry 
An entry in the FILE SECTION of the DATA DIVISION that is composed of the 
level-indicator SD, a file-name, and a set of file clauses as required. 


source 
The symbolic identification of the originator of a transmission to a queue. 


source item 
An identifier designated by a SOURCE elise that provides the value of a printable item. 


source program 
A program coded in a language that must be translated into machine language before 
execution. The translator program is usually a compiler. 


SOURCE-COMPUTER 
The name of an ENVIRONMENT DIVISION paragraph describing the computer 
environment within which the source program is compiled. 


special character 
(ANDIPS) A graphic Seaeacier in a character set that is not a letter, not a digit, and nota 
space character. 


special registers 
| Compiler-generated storage areas whose primary use is 5 to store values for specific 
COBOL features. 


special-character word 
A reserved word that is an avithmede operator or a relational character. 


SPECIAL-NAMES 
The name of an ENVIRONMENT DIVISION paragraph in which implementor-names 
are related to user-specified mnemonic-names. 


standard data format 
The concept used to describe the characteristics of data ina DATA DIVISION. The data 
characteristics are expressed in a format oriented to the appearance of the data ona 
printed page, rather than a format oriented to the manner in which data are stored 
internally in the computer or on a particular external medium. 


start of Kanji (SOK) character 
A character that signals the beginning of a Kanji character string. Synonym for 
start-of-double-octet (SDO) character. 


start-of-double-octet (SDO) character 


A character that signals the beginning of a double-octet character string. Synonym for: 
start of Kanji (SOK) character. 
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statement . 
A syntactically valid combination of words and symbols written in the PROCEDURE 
DIVISION and beginning with a verb. 


subfile 
- A logical, hierarchical division of a file. 


subject of entry 
An operand or reserved word that appears immediately after the level indicator or the 
- level-number in a DATA DIVISION entry. 


subprogram 
See called program. 


subqueue 
A logical, hierarchical division of a queue. 


subscript 
An integer whose value identifies a particular element in a table. 


subscripted data-name . 
An identifier composed of a data-name followed by one or more subscripts enclosed in 
parentheses. 


sum counter 
A signed numeric data item established by a SUM clause in the REPORT SECTION of 
the DATA DIVISION. The sum counter is used by the Report Writer Control System 
(RWCS) to contain the result of designated summing operations that take place during 
report production. 


switch-status condition . 
The proposition, for which a truth value can be determined, that an implementor-defined 
switch has been set to an ON or OFF status. 


system-name 
A word used to communicate with the operating environment. 


T 


table 
A one-dimensional or multidimensional structure in which like data items are stored. 
Each data item can be uniquely identified and accessed by means of its location in the 
table; identification and access procedures vary according to the language or product. 


table element 
A data item that belongs to the set of repeated items that make up a table. 


TADS 
_ See Test and Debug System. 
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TCP/IP 
See Transmission Control Protocol/Internet Protocol. 


terminal : 
The originator of a transmission to a queue or the receiver of a transmission from a 
queue. 8 


Test and Debug System (TADS) 
A Unisys interactive tool for testing and debugging programs and libraries. TADS 
enables the programmer to monitor and control the execution of the software under 
testing and examine the data at any given point during program execution. 


text-name 
A user-defined word that identifies library text. 


text-word 
A character or a sequence of contiguous characters in a library, source, or program, or in 
pseudotext. A text-word can be a separator (other than a space), a pseudotext delimiter, 
or an opening or closing delimiter for a nonnumeric literal. The right parenthesis and 
left parenthesis characters are always considered text-words. A text-word can also be a 
literal or any other sequence of contiguous COBOL characters except comments and the 
word COPY, bounded by separators, that is neither a separator nor a literal. 


TPS ; 
See transaction processing system. 


transaction processing system (TPS) | 
A Unisys system that provides methods for processing a ahah volume of transactions, 
keeps track of all input transactions that access the database, enables the user to batch 
data for later processing, and enables transactions to be processed on a database that 
resides on a remote system. 


Transmission Control Protocol/Internet Protocol (TCP/IP) 
A family of protocols that were originally developed for use in a Department of Defense 
network, and which have been widely adopted as standard protocols for multivendor 
networks. The applications protocols typically supported by TCP/IP are File Transfer 
Protocol (FTP), Simple Mail Transfer Protocol (SMTP), and Telnet. 


truth value 


The representation of the evaluation results of a condition in terms of one of two values: — 
TRUE or FALSE. 


U 


unary operator 
A plus sign (+) or a minus sign (—) preceding a variable or a left parenthesis in an 
arithmetic expression and that has the effect of multiplying the expression by + 1 or -1, 
respectively. 


A module of mass storage, the dimensions of which are determined by each implementor. : 
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user-defined word 
A word that must be supplied by the user to satisfy the format of a clause or statement. 


" 


variable 
An object in a program whose value can be changed during program execution. 


verb 
A word that expresses an action to be taken by a COBOL compiler or object program. 


“ 


WAN 
See wide area network. 
WFL 
See Work Flow Language. 
wide area network (WAN) 
A network that enables communications among various devices spread over a large area 
| _ (for example, devices located in different cities). 
Work Flow Language (WF L) 


A Unisys language used for constructing jobs that compile or run programs on A Series 
systems. WFL includes variables, expressions, and flow-of-control statements that offer 
the programmer a wide range of capabilities with regard to task control. 


WORKING-STORAGE SECTION 


The section of the DATA DIVISION that describes working-storage data items, either 
noncontiguous items or working-storage records, or both. 


Z 


zone portion 
The high order, or most significant, 4 bits of a byte. Contrast with digit portion. 


7 


77-level description entry 
A data-description entry that describes a noncontiguous data item with the level-number 
77. 
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A, edit character in PICTURE clause, 6-16, 


6-17, 6-18, 6-19 
A Series libraries, 15-1 
abbreviated combined relation conditions, 
8-23 
abnormal termination 
method of investigation, 17-27 
SIZE ERROR phrase, 8-25 
subscript out of range, 6-13 
table element out of range, 7-27 
with SET statement, 9-117, 9-119 
ACCEPT MESSAGE COUNT statement, 
14-19 
ACCEPT statement, 9-1 
and SPECIAL-NAMES paragraph, 5-7 
in communication module, 14-1 
ACCEPT-CLOSE phrase, in RESPOND 
statement, 9-103 
ACCEPT-OPEN phrase, in RESPOND 
statement, 9-103 
ACCEPTEVENT task attribute, 9-159 
access, (See file access) 
ACCESS MODE clause, 5-13 
indexed I/O, 5-22 
relative I/O, 5-19 
sequential I/O, 5-15 
ACTUAL KEY clause 
for specifying a subfile index, 3-2 
in AWAIT-OPEN statement, 9-10 
in CLOSE statement, 9-32, 9-34, 9-106 
in OPEN statement, 9-82 
in READ statement, 9-95, 9-96 
in RESPOND statement, 9-104 
in SEEK statement, 9-116 
in SELECT clause, 5-13 
sequential I/O, 5-15 
ADD statement, 9-3, (See also addition) 
storing results in multiple fields, 8-27 
with SIZE ERROR and 
CORRESPONDING ee 8-26 
addition, 8-6 
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arithmetic symbol for, 8-6 
cumulative totals with GIVING phrase, 
9-3 
reserved word for, 2-10 
ADDS, vi 


Advanced Data Dictionary System (ADDS), vi 


ADVANCING phrase 
in SEND statement, 14-28 
in WRITE statement, 9-162 
AFTER ADVANCING phrase 
in SEND statement, 14-26 
in WRITE statement, 9-167 
AFTER phrase 
in INSPECT statement, 9-60 
in SEND statement, 14-29 
in USE statement, 9-152 
in WRITE statement, 9-161 
ALGOL parameters 
for passing arrays, 7-23 
for tasking calls (table), 9~14 
using RECEIVED clause with, 7-34 
ALGOL typed procedure, 15-8 
alignment 
of data, 6-9 
rules for VALUE clause, 7-48 
when moving data, 9-69 
with JUSTIFIED clause, 7-22 
with USAGE IS INDEX a 7-45 
of decimal point 
in division, 9-47 
in editing, 6-18 
with ROUNDED phrase, 8-25 
of display characters, 7-44 
of elementary items 
with SYNCHRONIZED clause, 7-39 
of group items, 6-2 
ALL figurative constant, (See figurative 
constants) 
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in MOVE ALL literal construct (example), 
2-7 
with undigit literals, 2—18 
ALL phrase 
in INSPECT statement, 9-54 
in USE FOR DEBUGGING statement 
PROCEDURES phrase, 11-2 
REFERENCES phrase, 11-2 
ALLOW statement, 9-5 
with ATTACH statement, 9-41 
with DETACH statement, 9-41 
alphabet-name 
as a user-defined word, 2-12 
in SPECIAL-NAMES paragraph, 5-7 
alphabetic data items 
in PICTURE clause, 7-30 
types of, 6-5 
ALPHABETIC identifier, 8-18 
alphabetic truthset, 16-7, 16-17 
alphanumeric 
characters, translating, 16— 
data items 
in PICTURE clause, 7-30 
types of, 6-5 
file-attribute identifiers, 3—4 
hexadecimal characters, 2-17 
literal 
in Symbolic ID compiler control option, 
17-40 
using quotation marks with (example), 
2-14 
alphanumeric-edited data items 
rules for, 7-30 
types of, 6-5 
ALSO phrase, 5-9 
ALTER statement, 9-7 
in GO TO statement, 9-51 
alternate keys, 5-23 
when reading records, 9-94 
when replacing records, 9-109 
when writing records, 9-166 
ALTERNATE RECORD KEY clause 
_ in SELECT clause, 5-15 © 
indexed I/O, 5-23 
AND logical operator 
in abbreviated combined conditions, 8-23 
meaning of, 8-21 
ANSI-74 
compatibility, 1-1 
evaluating compliance with, 17-22 
application-specific keywords, B-6 
area A in source program, 1-6 


Index—2 


area B in source program, 1-6 
areas, use of file attributes to account for 
number of, 3-4 
arithmetic 
expressions 
assigning results to identifier, 9-34 
combinations (table), 8-7 
comparing numeric operands, 8-16 
order of precedence, 8-7 
types of, 8-6 
functions, 8-8 
operands 
data descriptions for, 8-27 
operators oy 
reserved word for, 2-10 
types of, 8-6 
statements 
overview, 8-26 
storing results in multiple fields, 8-27 
arithmetic-expression option for port files, 
3-3 
arrays, (See tables) 
in CALL statement, 9-15 
in communication module, 14-3 
passing parameters, lower-bound, 7-23 
AS GLOBAL PROCEDURE phrase, in USE 
statement, 9-155 
ASCENDING KEY phrase, in OCCURS 
clause, 7-25 
ASCENDING phrase 
in MERGE statement, 9-66 
in SORT statement, 9-123 
ASCII 
and EBCDIC character sets, C-1 
in SPECIAL-NAMES paragraph, 5-7 


- ASCII-to-EBCDIC translation table, 5-8 


ASSIGN clause, 5-13 
indexed I/O, 5-22 
relative I/O, 5-18 
sequential I/O, 5-15 
~ sort-merge, 5-24 
ASSOCIATED-DATA phrase 
in CLOSE statement, 9-32 
in OPEN statement, 9-81 
in RESPOND statement, 9-103 
ASSOCIATED-DATA-LENGTH phrase 
in CLOSE statement, 9-31 
in OPEN statement, 9-81 
in RESPOND statement, 9-103 
asterisk (*), edit character in PICTURE 
clause, 6-18 
asynchronous processes 
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acquiring a lock, 9-62 
after task detachment, 9-41 
communicating by using CAUSE 
statement, 9-19 
priority handling, 9-63 
releasing a lock, 9-139 
starting 
with PROCESS statement, 9-92 
with RUN statement, 9-110 
task-attribute identifiers in, 3-6 
At End condition, 5-27 
for indexed I/O, 5-82 
for relative I/O, 5-30 
for sequential I/O, 5-27 
AT END phrase . . 
in READ statement, 9-94, 9-95, 9-99 
in RETURN statement, 9-106 
in SEARCH statement, 9-111 
at sign (@) 
as a Separator, 2~2 
for undigit literals, 2-17 
ATTACH statement, 9-7 — 
with DETACH statement, 9-41 
with interrupts, 9-6 — | 
ATTRIBUTE clause, general format for 
file-attribute identifiers, 3-3 ~ 
task-attribute identifiers, 3-6 
attributes 
of files, 3-2 
assigning initial values, 7-10 
dynamically changing for port files, 7-12 
of libraries, 15-12 
of tasks, 3-6 
OPTION, 3-9 
STATUS, 9-41 
out-of-range errors with, 9-22 
audit considerations, 9-164 
AUTHOR paragraph, 4-1 
automatic file allocation, 7-8 
AUTORM (autoremove) system option, 9-29 
in relative and indexed files, 9-30 
AVAILABLE EXTEND phrase in OPEN 
. statement, 9-75, 9-76 
AVAILABLE phrase 
in AWAIT-OPEN statement, 9-9 
in OPEN statement, 9-75, 9-76, 9-77, 
9-80 
AWAIT-OPEN statement 
examples, 9~11 
syntax, 9-9 
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B, edit character in PICTURE clause, 6-16 
backup files 
CODE clause, 12-3 
when printing with PB (Printer Backup) 
WEL statement, 12-5 
with sequential file organization, 5-13 
base number system, affected by USAGE 
clause, 7-46 
BDREPORT clause, in Report Writer, 12-4 
BEFORE ADVANCING phrase 
in SEND statement, 14-26 
in WRITE statement, 9-167 


BEFORE phrase 


in INSPECT statement, 9-60 
in SEND statement, 14-29 
in WRITE statement, 9-161 
BINARY phrase 
in data-description entry, 7-18 
in USAGE clause, 7-42 
binary search, 9-115 
BINARY TRUNCATED phrase 
in data-description entry, 7-18 
in USAGE clause, 7-42 
BINARYCOMP compiler control option, 
17-18 
Binder, (See bound procedures) 
BINDINFO compiler control option, 17-18 
binding 
declaring lower-bound formal parameter 
for, 7-23 
identifying program to be bound, 9-156 
placing information for binding in a code 
file, 17-18 
programs as procedures, 9-16 
bit manipulation, 9-72 
blank lines in a source program, 1-13 
BLANK WHEN ZERO clause 
in data-description entry, 7-20 
in Report Writer, 12-22 
overview, 7-20 
with initialization process, 7-48 
with zero-suppression symbol, 7-29 
BLOCK CONTAINS clause 
-general format of, 7-6 
in file-description (FD) entry, 7-6 
blocking factor, 7-6 
blocks 
Short Block condition 
for indexed I/O, 5-32 
for relative I/O, 5-30 
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for sequential I/O, 5-29 
specifying size of, 7-6 
using file attributes to account for number 
of, 3-4 
Boolean 
_ compiler control options, 17-8 
file-attribute identifiers, 3-5 
task attributes, 9-22, 9-121 
BOTTOM margin in file-description (FD) 
entry, 7-14 
bottom margin in LINAGE clause, 7-15 
bound procedures, 17-41 
naming identifiers received, 8-1 
passing lower-bound parameters, 7-23 
using EXIT statement for ererrumne from, 
9-49 
using GLOBAL clause, 7-21 
using programs as, 7-35 
using RECEIVED clause, 7~34 
using VALUE clause, 7-49 
bound program, parameters for (table), 9-16 
Boundary Violation condition 
for indexed I/O, 5-32 
for relative I/O, 5-30 
braces in format notation (example), A-3 
brackets 
in format notation (example), A~-3 
in partial words, 9-72 
branching logic 
changing a GO TO statement, 9-7 
overview, 8-13 
with GO TO statement, 9-51 
with IF statement, 9-52 
- Break On Output condition 
for indexed I/O, 5-32 
for relative I/O, 5-31 
for sequential I/O, 5-29 
Broadcast Write error, 5-29 
broadcast write operation, 9-167 
buffers . 
1/0 error condition, 5-29 
in closing files, 9-29 
in communication module, 14~—2 
when writing records to port files, 9-169 
byte boundaries 
with display data items, 7-44 
with REDEFINES clause, 7-36 
with SYNCHRONIZED clause, 7-39 
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C 


CALL statement, 9-12, (See also libraries) — 


and CONTINUE statement, 9-35 
effect on library attributes, 15-13 
execution of, 9-13 
in Inter-Program Communication PC), 
13-4 
in libraries, 15-5 
relationship to PROCEDURE DIVISION 
parameters, 8-1 
restriction, 7-35 
with DETACH statement, 9-41 
with EXIT PROGRAM statement, 9-50 
with USAGE clause, 7-45 
CALL SYSTEM DUMP statement, 9-18 
CALL SYSTEM WFL statement, 9-18 
called program, 13-4 
calling program, 13-4 
CANCEL statement 
in Inter-Program Communication (IPC), 
13-5 
in libraries, 15-5, 15-10 
CANDE, (See Command and Edit 
(CANDB)) 
CARD file, used by compiler, 17-13 
CAUSE statement, 9-19 
CCR, (See compiler control record (COR) 
CCS, (See coded character set) 
CCSTOCCS_ TRANS TEXT procedure, 
16-6, 16-31 
cesversion, 16-1 
designating, 16-16 
escapement rules for rearranging text, 
16-102 
name, obtaining, 16-28, 16-95 
names and numbers, obtaining list of, 
16-34 
number, obtaining, 16-93 
system default, definition, 16-5 
system default, obtaining name and 
number of, 16-37 
CCSVERSION clause, 16-7 
CCSVSN_NAMES NUMS procedure, 16-34 
CD, (See communication-description (CD) 
entry) 
CD-name, as user-defined word, 2-12 
CENTRALSTATUS procedure, 16-37 
CENTRALSUPPORT library, 16-2 
calls to 
status of, 16-30, 16-116 
input parameters, 16-28 
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level of, 16-37 
minimizing calls to, 16-81 
procedures, 16-20 
calling, 16-27 
CENTRALSUPPORT library procedures 
functions of (table), 16-21, 16-23 
CF phrase, (See CONTROL FOOTING 
phrase, in Report Writer) 
CH phrase, (See CONTROL HEADING 
phrase, in Report Writer) 
CHANGE ATTRIBUTE statement, changing 
library attribute value, 15-13 
CHANGE statement, 9-20 
when opening subfiles, 7-12 
with optional word VALUE, 9-21, 9-22 
channel number 
naming in SPECIAL-NAMES paragraph, 
5-7 
specifying in WRITE statement, 9-162, 
9-168 © 
character 
basic unit of COBOL, 2-1 
for editing, 7-31 
manipulation, 9-72 
character advance direction, 16-102 
character code set 
defining, 5-7 
from external device, 7-16 
character escapement direction, 16-102 
character set, 16-1, 16—4 
ASCII and EBCDIC, C-1 
for comments, 2-1 
for nonnumeric literals, 2-1 
standard, 2-1 
character string 
definition, 2-3 
valid characters for, 2-1 
characters per line 
in convention, determining, 16-61 
CHARACTERS phrase, in INSPECT 
statement, 9-54 
check-protect asterisk (*) 
edit character in PICTURE clause, 6-19 
in zero-protection editing, 6-22 
checkpoints, (See rerun points) 
class condition 
precedence of, 8-24 
- simple, 8-18 
CLEAR compiler control option, 17-19 
close file disposition, 9-27 
close reel disposition, 9~28, 9-29 
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CLOSE statement, 9-22, (See also closing a 
file) 
executing, for sequential files, 9-27 © 
for port files (examples), 9-32 
for relative and indexed I/O, 9-30 
when status values are updated 
for indexed I/O, 5-31 
for relative I/O, 5-30 
for sequential I/O, 5-27 
with multiple-file tapes, 5-26 
with nonreel file, 9-23 
with port files, 3~2 
with sequential files in READ and WRITE 
statements, 9-28 
CLOSE-DISPOSITION ABORT phrase, 9-31 
CLOSE-DISPOSITION ORDERLY phrase, 
9-31 
closing a file, 9-22, (See also CLOSE 
statement) 
automatically when merging files, 9-65 
CMP phrase, (See COMPUTATIONAL 
phrase) 
CNV_CURRENCYEDIT COB procedure, - 
16-44 
CNV_CURRENCYEDITTMP COB 
procedure, 16-41 
CNV_DISPLAYMODEL COB procedure, 
16-47 
CNV_FORMATDATE COB procedure, 
16-53 
CNV_FORMATDATETMP COB procedure, 
16-50 


- CNV_FORMATTIME COB procedure, 


16-58 


(CNV_FORMATTIMETMP COB procedure, 


16-56 
CNV_FORMSIZE sehesatenat 16-61 
CNV. NAMES procedure, 16-64 
CNV_SYMBOLS procedure, 16-67 
CNV_SYSTEMDATETIME COB procedure, 
16-78 
CNV_SYSTEMDATETIMETMP COB 
procedure, 16-75 
CNV_TEMPLATE COB procedure, 16-81 
CNV_  VALIDATENAME procedure, 16-84 
COBOL68 
parameters 
for tasking calls (table), 9-14 
using RECEIVED clause with, 7-34 
COBOL74 
compatibility with ANSI standard, vii 
CODE clause 
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for identifying the line of a file, 12-3 
in report-description (RD) entry, 12-3 
CODE compiler control option, 17-19 _ 
during compilation, 17-15 
CODE file, used by compiler, 17-15 
CODE SEGMENT-LIMIT clause, 5-4 
code segmentation, printing information 
about, 17-15 
CODE-SET clause 
function, 7~16 


syntax in file-description (FD) entry, 7-16 


with SIGN clause, 7-38 
coded character set, 16-4 
name, obtaining, 16—95 
names and numbers, obtaining list of, 
16-34 
number, obtaining, 16-93 
translating from one to another, 16-6, 
16-31 
coding for readability (example), 1-9 
coding form 
area A, 1-6 
area B, 1-6 
sequence number area, 1-6 
collating sequence, 16—2 
assignment of, 5-4 
associating with alphabet-name, 16-16 
comparing key data 
_ in MERGE statement, 9-66 
in SORT statement, 9-124 
figurative constants in, 2-6 
rules for explicitly setting, 5-7 
system-wide, designating, 16-16 
use in comparing nonnumeric operands, 
8-16 . 
COLLATING SEQUENCE phrase 
in MERGE statement, 9-64 
in SORT statement, 9-122 
colon, in partial words, 9-72 . 
COLUMN NUMBER clause, in Report 
Writer, 12-22, 12-23 
combining files, (See merging files) 
comma (,) 
as edit character in PICTURE clause, 6-18 
as separator, 2-2 
in format notation, A-—2 
in place of decimal point, 5-7 
Command and Edit (CANDE) 
continuing a program, 9-132 
LIST compiler control option default, 
17-15 
starting compilation from, 17-14 
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using ERRORLIST compiler control 
option, 17-21 
comment line 
in COPY statement, 9-39 
with COPY statement in compilation 
listing, 9-39 
comments 
character set for, 2-1 
coding (example), 1-10 
in format notation, A-2 
in source program, 1-10 
punctuation for, 2-3 
comments-entry, in DATA-COMPILED 
paragraph, 4-3 
communication module, 14-1 
accepting messages in a queue, 14~—19 
communication-description (CD) entry, 
14-6 
DATA DIVISION, 14-6 
data-description entries, 14-8 
DCILIBRARY, 14-1 
DCILIBRARY entry point (example), 14-4 
enabling two terminals (example), 14-17 
getting information about data in a queue, 
14-22 
inhibiting data transfer, 14-20 
PROCEDURE DIVISION, 14-19 
sample program, 14—17 
specifying device type, 14-3 
status key condition 
01-level (figure), 14-11 
02-level (figure), 14-16 
transferring data to or from a queue, 
14-21 
writing to a queue, 14-25 
COMMUNICATION SECTION, 14-6 
defining initial value, 7-46 
overview, 7-1 
rules for using VALUE clause in, 7-49 
communication-description (CD) entry, 14-6 
Communications Management System 
(COMS), vi 
COMP phrase, (See COMPUTATIONAL 
phrase) 


- comparing operands, 8-16 


comparing text 

in localized applications, 16-98 
COMPARISON clause, 5~22 
comparisons, using relation conditions, 8-15 


‘ compile-time 


switch, in debug module, 11~1 
warnings with table errors, 6-13 
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compiler 


attributes for, 7-10 
byte alignment by, 6-2 
controlling with compiler control options, 
. 17-7 
files 
attributes for, 17-13 
input, 17-13 
output, 17-15 
overview, 17-12 
overview, 1-1 
role in merging files, 9-67 
task attributes supplied by, 3-7 
- unexpected results with use of file 
attributes, 7-10 


compiler control options, 17-7 


-action indicators, 17-10 
activation of, 17-10 
BINARYCOMP, 17-18 
BINDINFO, 17-18 
Boolean, 17-8 
CLEAR, 17-19 
CODE, 17-15, 17-19 
COMPILERDEBUG, 17-19 
DEBUG, 17-19 
DELETE, 17-20 
DOUBLE, 17-20 
ERRORLIMIT, 17-21 
ERRORLIST, 17-21 
FEDLEVEL, 4-2, 15-1, 17-22 
for libraries, 15-14 
FREE, 11-1, 17-22 
GLOBAL, 17-23 

using (example), 7-21 
GLOBALTEMB, 17-24 
immediate, 17-9 
in source program, 1-13 
INFO, 17-25 


NOXREFLIST, 17-31 
OMIT, 17-32 
OPT or OPTIMIZE, 17-82 
OWN, 17-33 

relation to OWN clause, 7-28 
OWNTEMB 17-34 
PAGE, 17-34 | 
placement of, 9-39, 17-10 
SEPCOMP 17-35 
SEQ or SEQUENCE, 17-36 
SEQCHECK, 17-35 
Sequence Base, 17-37 
Sequence Increment, 17-37 
SHARING, 17-38 
SPEC, 17-39 
STATISTICS, 17-39 
SUMMARY, 17-40 
Symbolic Id, 17-40 
syntax, 17-9 
TADS, 17-40 
TARGET, 17-42 
TEMPORARY, 17-43 » 
USER, 17-44 
value, 17-8 
VOID, 17-44 
WARNFATAL, 17-45 
WARNSUPR, 17-45 
XDECS, 17-45 
XREF, 17-46 
XREFFILES, 17-46 
XREFS, 17-47 


compiler control record (CCR), 17-7 


<compiler control record>, 17-9 
compiler-directing sentences, 8-5 


Index 


COMPILERDEBUG compiler control option, 


. 17-19 
compiling 
at lexicographic level 3 


LEVEL, 5-14, 17-26 

LIB$ or LIBDOLLAR, 17-26 
LINEINFO, 17-26, 17-27 
LIST, 17-27 

LIST$ or LISTDOLLAR, 17-27 
LISTDELETED, 17-28 
LISTOMITTED, 17-28 
LISTP, 17-28 

LIST1, 17-28 

MAKEHOST, 17-29 

MAP, 17-15, 17-29 


for using global variables, 7-21 

to use local variables, 7-23 
code customized for a machine, 17-42 
input and output during (figure), 17-12 

- separate compilation method, 17-4 
setting the error limit for, 17-21 
using COPY statement for text 
- replacement, 9-36 
complex conditions, 8-20 
abbreviated combined relation, 8-23 
_ combined and negated combined, 8-21 


MERGE, 17-30 condition evaluation rules, 8-24 
NEW, 17-15, 17-380 negated simple, 8-21 
NEWID, 17-31 COMPUTATIONAL phrase 
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in data-description entry, 7-18 
in USAGE clause, 742 — 
with group-items, 7-43 
COMPUTE statement, 9-34 , 
storing results in multiple fields, 8-27 
using extended functions with, 8-9 
computer-name, definition, 2-12 
COMS (Communications Management 
System), vi 
concatenation of data, 9-133 
condition evaluation rules, 8-24 
condition-name, 7—51 
as a user-defined word, 2-12 
coding of (example), 7-52 
condition, 8-19 
precedence of, 8-24 
defining, 2-12 
initial value, 7-46 
qualification of, 6-7 
rules for using VALUE clause with, 7-52 
conditional expressions, 8~18 
comparing 
Kanji operands, 8-17 
nonnumeric operands, 8-16 
complex, 8-20 
abbreviated combined relations, 8-23 
combined and negated combined, 8-21 
negated simple, 8-21 
in PERFORM statement, 9-84, 9-85 
simple, 8-14 
class, 8-18 
condition-name, 8-19 
event-identifier, 8-20 
relation, 8-14 
sign, 8-19 
with index-names, 8-17 
with SEARCH statement, 9-112 
conditional sentences and statements, 8-4 
conditional statements, with IF statement, 
9-52 
' conditional variable 
defining, 2~12 
testing condition of, 8-19 
using FILLER keyword with, 7-20 
conditions 
complex, 8-20 
abbreviated combined relations, 8-23 
combinations (table), 8-22 
combined and negated combined, 8-21 
negated simple, 8-21 
simple, 8-14 
class, 8-18 
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comparing numeric operands, 8-17 
condition-name, 8-19 
event-identifier, 8-20 
relation, 8-14 
sign, 8-19 
CONFIGURATION SECTION, 5-2 
CONNECT-TIME-LIMIT phrase, in OPEN . 
statement, 9-81 
connectives, 2—4 
constants 
defining value of, 7-46 
in WORKING-STORAGE SECTION, 7-53 
using as data, 7-1 
CONTENT phrase, in data-description entry, 
7-18 
context-sensitive keywords, B-6 
continuation line 
coding (example), 1-11 
in source program, 1-10 
CONTINUE statement, 9-35 
execution of, by calling program, 9-13 
with EXIT PROGRAM statement, 9-50 
continuing a program from CANDE, 9—132 
control breaks in Report Writer, 12-6 
CONTROL clause, in report-description (RD) 
entry, 12-3, 12-5 
CONTROL FOOTING phrase, in Report 
Writer, 12-13, 12-16, 12-18 
CONTROL HEADING phrase, in Report 
Writer, 12-13, 12-16, 12-17 
control-point items, 9~14 
CONTROL-POINT phrase 
as synonym for USAGE IS TASK clause, 
7-43 
in data-description entry, 7-18 
in USAGE clause, 7-42 
convention, 16-1 
characters per line, 16-61 
creating, 16-11 
lines per page, 16-61 
provided by Unisys, 16-11 
system default, obtaining name of, 16-37 
total number on system, 16-64 
verifying presence of, 16-84 
convention names 
listing, 16-64 
obtaining, 16-28 


CONVENTION phrase, 7-39 


CONVENTION task attribute, 16-4 
conventions 

business and cultural, 16-11 

for localization, establishing, 16-4 


8600 0296-000 


formatting data items for, 16-16 
CONVERSATION AREA clause, 14-7, 14-13 
conversion of data 

editing symbol, 6-16 

when moving, 9-69 
copy descriptors, for OWN variables, 7-28 
COPY library files, used by compiler, 17-14 
COPY statement, 6-9, 9-36 

affected by compiler control option 

placement, 17-10 

as compiler-directing verb, 8-5 

coding of (example), 9-40 

comment lines in, 9-39 

cross-referencing information for, 17-4 

during compilation, 17-14 

replacing text in object program, 9-38 
coroutine, with EXIT statement, 9-49 
CORR phrase, (See CORRESPONDING 

phrase) 
CORRESPONDING phrase, 8-26 

in ADD statement, 9-4 

in MOVE statement, 9-72 

in SUBTRACT statement, 9-138 
COUNT phrase, in UNSTRING statement, 

9-140 
counters, sum, 12-25 
CP phrase, (See CONTROL-POINT phrase) 
CR, sign-control symbol for editing, 6-18 
critical block exit, 9-92 
cross-reference 
NOXREFLIST compiler control option, 
17-31 

using cross-reference files, 17—1 

XDECS compiler control option, 17-45 

XREF compiler control option, 17-46 

XREFFILES compiler control option, 

17-46 

XREFS compiler control option, 17-47 
crunch file disposition, 9-28 — 
CRUNCH phrase 


in CLOSE statement for nonreel files, 9-24 


in MERGE statement, 9-64 
in SORT statement, 9-122 
currency display, international formatting, 
16-14 
CURRENCY SIGN clause 
in SPECIAL-NAMES paragraph, 5-9 
CURRENCY SIGN clause, in 
SPECIAL-NAMES paragraph, 5-9 
current-record pointer, 3-6 
effect on record deletion, 9-40 
when writing to a file, 9-160 _ 
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with sequential file access, upon reading, 
9-94 


D 


data 
alignment of, 6-9 
categories of, 7-1 
classification of, 6-5 
concepts, vii 
contiguous, creating multiple fields from, 
9-139 
conversion, 9-69 
defining 
file structure, 7-3 
hierarchy with level-number, 6-4 
ensuring integrity of in libraries, 17-26 
initializing, 7-46 
joining, 9-133 
translating from one coded character set to 
another, 16-31 
data classes, 16-6 
data communications interface (DCD, 14-1 
data communications protocols, international, 
16-1 
data descriptors, task items, 7-43 _ 
DATA DIVISION 
localization syntax, 16-16 
overview, 1-2 
REPORT SECTION of, 12-1 
subdivisions of, 7-1 
syntax, 7-2 
Data Error condition 
for indexed I/O, 5-32 
for relative I/O, 5-30 
for sequential I/O, 5-29 
data items 
as conditional variables, 2-12 
considerations for handling, 6-5 
defining 
as alphabetic, 7-30 
as alphanumeric, 7-30 __ 
as alphanumeric-edited, 7-30 
as Kanji, 7-31 © 
as Kanji-edited, 7-31 
as numeric, 7-30 
as numeric-edited, 7-30 
in Inter-Program Communication (IPC), 
13-2 
intermediate, in arithmetic operations, 
8-27 
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internal representation of, 7-44. 
maximum size of, 7-19 
moving system date or time to, 16-17 
relationship of class and category (table), 
6-6 
using USAGE clause to specify format of, 
7-41 . 
Data Management System II (DMSID), vi 
DATA RECORDS clause 
coding of (example), 7-13 
function, 7~13 
in file-description (FD) entry, 7-13 
DATA-BASE SECTION, 7-1 
data-description entry 
content of, 6—1 
creating multiple fields for, 9-139 
for communication module, 14-8 
format of level numbers in, A-2 
function, 7-17 
redescribing a memory area, 7—35 
data-name 
as a user-defined word, 2-12 
qualification of, 6-7 
data-name clause, 7-19 
date | 
formatting by convention and language, 
16-53 
formatting by template, 16-50 
international formatting, 16-12 
numeric, display model, 16-47 
system-provided 
formatting by convention, 16-78 
formatting by template and language, 
16-75 
template, creating or modifying, 16-50 
DATE special register, 2-9 
in ACCEPT FROM statement, 9-2 
DATE-COMPILED paragraph, 4-1, 4-3 
DATE-WRITTEN paragraph, 4-1 
day boundary, 16-75 
day name, 2-10 
DAY special register, 2-9 
in ACCEPT FROM statement, 9-2 
day-of-week value, 2-10 
DB, sign-control symbol for editing, 6-18 
DCI (Data Communications Interface), 14-1 
DCIENTRYPOINT, entry point for the 
DCILIBRARY, 14—1 
DCILIBRARY, 14-1 
DE phrase, (See DETAIL phrase) 
DEBUG compiler control option, 17-19 
debug module, 11-1 
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DEBUG-CONTENTS, 11-6 
DEBUG-ITEM, 2-9, 11-5 
DEBUG-LINE, 11-6 
DEBUG-NAME, 11-6 
DEBUG-SUB-1, 11-6 
_DEBUG-SUB-2, 11-6 

DEBUG-SUB-3, 11-6 

DEBUG-ITEM 
in debug module, 11-5 
special register, 2-9 

debugging . 
with cross-reference files, 17-4, 17-46 
with debug module, 11-1 . 
with Test and Debug System (TADS), 

17-40 


- debugging line 


coding example, 1-11 
in COPY statement, 9-39 
symbol for, 11-9 
DEBUGGING MODE option 
in SOURCE-COMPUTER paragraph, 5-2 
DEBUGGING MODE option, in 
SOURCE-COMPUTER paragraph, 
11-2 
decimal point 
defining, 5-10 
editing symbol for, 6-17 
when aligning data, 6-9 
with floating insertion editing, 6-21 
with special insertion editing, 6-20 
DECIMAL-POINT IS COMMA clause, in 
SPECIAL-NAMES paragraph, 5-10 
DECLARATIVES SECTION 
coding of (example), 8-3 
in Report Writer, 12-33 
location in source program, 1-6 
restrictions for libraries, 15-2 
syntax, 8-2 
USE AS INTERRUPT clause 
in DETACH statement, 9-41 
in DISALLOW statement, 9-42 
used as an interrupt procedure, 9-157 
with ALLOW statement, 9-6 
default 
block size, 7-6 
ecsversion, 16-5 
disk area for sorting files, 9-125 
file organization, 5~15 
in format notation, A—2 
memory allocation for sorting files, 9-124 
number of I/O areas, 5-15 
number of tapes for sorting, 5-24 
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object-code segment size, 5-4 
parameter type, 7-34 
settings for localization, 16-2, 16-3 
USAGE clause, 7-44 
DEFAULT DISPLAY phrase, in 
SPECIAL-NAMES paragraph, 5-10 
default settings 
for internationalization, 16-3 
DEFAULT SIGN clause, 5-10 
DELETE compiler control option, 17-20 
DELETE statement, 9-40 
open modes, 9-79 
when status values are updated 
for indexed I/O, 5-31 
for relative I/O, 5-30 
DELIMITED BY phrase 
in STRING statement, 9-134 
in UNSTRING statement, 9-140 
DELIMITER phrase, in UNSTRING 
statement, 9-140, 9-143 
dependent processes, (See processes) — 
dependent tasks, (See tasks) 
DEPENDING ON phrase, in OCCURS 
clause, 7-26 
DESCENDING KEY phrase, in OCCURS 
clause, 7-25 
DESCENDING phrase 
in MERGE statement, 9-66 
in SORT statement, 9-124 
DESTINATION COUNT phrase, 14-12, 
14-13 
DESTINATION TABLE OCCURS phrase, 
14-12 
DETACH statement, 9-41 
using ATTACH statement with, 9-41 
DETAIL phrase 
in Report Writer 
relation to GENERATE statement, 
12-17, 12-30 
syntax, 12-13 
syntax for TYPE clause, 12-16 
devices 
assigning ~ 
in indexed file organization, 5~21 
in relative file organization, 5-18 
in sequential file organization, 5-15 
external | 
specifying character code set, 7-16 
releasing, 9-29 
types of 
for sequential files, 5-15 
in communication module, 14-3 
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DISABLE statement 
in communication module, 14-1, 14-20 
with undigit literals, 2-18 
DISALLOW statement, 9-42 
with ALLOW statement, 9-5 
with ATTACH statement, 9-7 
with DETACH statement, 9-41 
disk files 
closing, 9-23 
for printer backup, 12-4 
for sorting or merging, 5-24 
with sequential file organization, 5-15 
with variable-length records, 78 
DISK SIZE clause 
in MERGE statement, 9-64 
in OBJECT-COMPUTER paragraph, 5-3 
in SORT statement, 9-122, 9-125 
DISPLAY phrase 
in data-description entry, 7-18 
in Report Writer, 12-13 
in USAGE clause 
character alignment of, 7-44 
syntax, 7-42 
DISPLAY statement 
and SPECIAL-NAMES paragraph, 5-7 
syntax, 9-43 
with POINTER task attributes, 3-8 
with undigit literals, 2-18 
DIV function, 8-8 
divide by zero, SIZE ERROR phrase, 8-25 
DIVIDE statement, 9-44, (See also division) 
storing results in multiple fields, 8-27 
with BY phrase, 9-46 
with edited items, 9-47 
with GIVING phrase, 9-45 
with INTO phrase, 9-46 
with REMAINDER phrase, 9-46 
division, 8-6 
arithmetic symbol ie 8-6, (See also 
DIVIDE statement) 
reserved word for, 2-10 
using DIV function for integer division, 8-8 
when Size Error condition occurs, 8-25 
division headers, location in source program, 
1-6 
DMSII (Data Management System I)), vi 
dollar currency symbol ($) 
defining, 5-9 
- edit character in PICTURE clause, 6-19. 
with fixed insertion editing, 6-20 | 
dollar options, (See compiler control options) 
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dollar sign ($), edit character in PICTURE 
clause, 6-19 
DONT-PARTICIPATE phrase, 9-10 
DOUBLE compiler control option, 17-20 
DOUBLE phrase 
as indication of internal floating-point 
format, 7-44 
in USAGE clause, 7-42 
double spacing of printed output, 17-20 
double-precision numeric format 
floating-point literals, 2-16 
in exponentiation, 8-7 
of DOUBLE data item, 7-44 
partial words, 9-111. 


using USAGE IS DOUBLE clause, 7-44 _ 


DOWN BY phrase 
in CHANGE statement, 9-21 
in SET statement, 9-118, 9-119 
DUMP statement, 9-18 
DUMPANALYZER utility, 17-18 
duplicate keys, 5-23 
condition 
for indexed I/O, 5-32 
results with SEARCH statement, 9-115 
Duplicate Keys 
condition 
for relative I/O, 5-30 
DUPLICATES phrase in indexed I/O, 5-23 
dynamic file access, 5-22, (See also file 
access) 
in indexed file organization, 5~22 
in relative file organization, 5-19 
open modes, 9-79 


E 


EBCDIC 
and ASCII character sets, C—1 
converting to or from, with CODE-SET 
clause, 7-16 
in SPECIAL-NAMES paragraph, 5-7 
EBCDIC-to-ASCII translation table, 5-8 
editing 
alignment of numeric-edited data, 6-10 
characters for sign-control, 6-18 
coding of (examples), 6-24 
fixed insertion (example), 6-20 
floating insertion, 6-21 
in division, 9-47 © 
in PICTURE clause, 7-30, 7-31 
meaning of symbols for, 6-16 
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methods and data types (table), 6-23 
precedence rules for, 7-32 
results of sign-control symbol (table), 6-21 
rules for performing, 6-19 
rules for VALUE clause, 7-48 
simple insertion (example), 6-19 | 
size considerations for, 6-16 
special insertion, 6-20 
using BLANK WHEN ZERO clause with 
numeric data, 7-20 
with RENAMES clause, 7-51 
zero-suppression, 6-22 
efficiency considerations in libraries, 15-7, 
15-11 
EGI, (See end-of-group indicator (EG]) 
ejecting a page 
with PAGE compiler control option, 17-34 
with slash (/) character, 1-10 
elementary items 
alignment in memory 
with SYNCHRONIZED clause, 7-39 ° 
as subdivision of record, 6-2 
coding of (example), 6-3 
declaring as 
alphabetic, 7-30 
alphanumeric, 7-30 
alphanumeric-edited, 7-30 
Kanji, 7~31 
Kanji-edited, 7-31 
numeric, 7-30 
numeric-edited, 7-30 
definition, 6-2 
in arithmetic expressions, 8-6 
justification of, 7-22 
PICTURE clause for, (See PICTURE 
clause) 
redefining in records 
with RENAMES clause, 7-50 
searching and replacing, 9-54, 9-55, 9-57 
size of, 7-31 
symbols used in editing, 7-31 


ellipses, in format notation (example), A-3 


ELSE phrase, with IF statement, 9-52 
EMI, (See end-of-message indicator (EMI)) 
ENABLE statement 
in communication module, 14—1, 14-21 
with undigit literals, 2-18 
END KEY phrase, in communication- 
description (CD) entry, 
14-7 
end of program, 8-3 
end-of-file (EOF) indicator, 7-8 
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. end-of-group indicator (EGD) 
transmission indicator schedule, 14~-28 
end-of-message indicator (EMI) 
in SEND statement, 14-26 
transmission indicator schedule, 14—28 
END-OF-PAGE phrase 
explanation of end-of-page condition, 
9-162 
in WRITE statement, 9-161 
end-of-reel indicator 
when not end-of-file (EOF), 9-94 
end-of-segment indicator (ESI) 
in SEND statement, 14-26 
transmission indicator schedule, 14—28 © 
end-of-task (EOT) indicator occurring with 
EXIT statement, 9-49 
- entry points 
DCIENTRYPOINT, 14-1 
entry-point-name, 4-2, 15-6 
overview, 15-1 
using CALL statement with, 9-15 
ENVIRONMENT DIVISION, 5-1 
coding of (example), 5-33 
in the debug module, 11-2 
localization syntax, 16-16 
overview, 1-2. 
EOE (See end-of-file (EOF) indicator) 
EOP phrase, (See END-OF-PAGE phrase) _ 
equal sign (=) . 
in format notation, A-3 
in relation condition, 8-15 
reserved word for, 2-10 
ERROR KEY clause in communication- 
description (CD) entry, 
14-13 
ERROR phrase 
in MERGE statement, 9-65 - 
in SORT statement, 9-123 
in USE statement, 9~152 
error values . 
for internationalization (table), 16-118 
ERRORFILE file, used by compiler, 17-16 
ERRORLIMIT compiler control option, 17-21 
ERRORLIST compiler control option, 17-21 
errors, (See abnormal termination, status 
reporting) 
critical block exit, 9-92 
data type incompatible, 8-28 
in communication module, 14-11 
Invalid Key condition 
in REWRITE statement, 9-110 
when deleting records, 9-40 
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parity 
when merging files, 9-65 
when sorting files, 9-123 
rounding, 9-35 
rules that apply to, in division, 9-47 
run-time, with CALL statement, 9-14 
STACK OVERFLOW fault, 9-85 
syntax 
for attribute out of range, 9-22 
printing of, 17-15 
when writing to error file, 17-21 
with SET statement, 9-121 
values returned by CENTRALSUPPORT 
library calls, 16-116 
when using SIZE ERROR phrase, 8-25 
with indexed I/O, 5-32 
with relative I/O, 5-30 
with sequential I/O, 5-28 
ERRORS file, used by compiler, 17-16 
escapement rules in ccsversion, 16-102 
ESI, (See end-of-segment indicator (ESD) 
evaluation rules, for arithmetic expressions, 
8-7 
EVENT identifiers 
for file attributes, 3-5 
for task attributes, 3-8 
EVENT item, dissociating a procedure from, 
9-41 
EVENT phrase 
in data-description entry, 7-18 
in USAGE clause | 
syntax, 7-42 
to interlock processes, 7-44 


‘event-identifier condition, 8-20 


events 
disallowing an interrupt, 9-42 
in Interrupt condition 
with ALLOW statement, 9-6 
with ATTACH statement, 9-8 
initiating with CAUSE statement, 9-19 
resetting after caused, 9-158 
testing for, 8-20 
- testing or turning off, with RESET 
statement, 9-102 
example program for 
comment lines coding, 1-11 
communication module, 14-17 
condition-name coding, 7-52 
continuation lines coding, 1-11 
controlling family substitution in libraries, 
15-17 
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DCI library entry point with eight 
parameters, 14—4 
debugging line coding, 1~12 
elementary and group items coding, 6-3 
ENVIRONMENT DIVISION coding, 5-33 
FD and DATA RECORDS clause coding, . 
7-13 
formatting a record, 6-5 
IDENTIFICATION DIVISION coding, 4-2 
library calls, 15-16 
one-dimensional table coding, 6-11 
readability, coding for, 1-9 
record layouts coding, 6-5. 
_ three-dimensional table coding, 6-12 
UNSTRING statement, 9-149 
using declaratives, 8-3 
using FORMATTED-SIZE feats: 8-9 
using Report Writer, 12-33 
VALUE OF clause coding, 7-12 
WORKING-STORAGE SECTION coding, 
7-54 
exception handling, 9-152 
EXCEPTION phrase, in USE statement, 
9-152 
EXCEPTIONEVENT task attribute, 9-159 
EXECUTE statement, (See RUN 
statement) 
execution status 
for indexed I/O, 5-24 
for relative I/O, 5-19 
for sequential I/O, 5-16 
execution time . 
assigning a device at, 9-29 
warning message, 15-11 
_ EXIT PERFORM statement, 9-50 
EXIT PROCEDURE statement, 9-49 
EXIT PROGRAM statement, 9-49 
and CONTINUE statement, 9-35 
execution of, in called program, 9-13 
in COBOL74 libraries, 15-4 . 
in Inter-Program Communication (IPC), 
13-6 
in libraries, 15-4 
EXIT statement, 9-49 
exponent, definition, 2-16 
exponentiation 
arithmetic symbol for, 8-6 © 
in arithmetic expressions, 8—7 
reserved word for, 2-10 
expressions 
arithmetic, 8-6 
use with port files, 3—3 
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conditional, 8-13 
formation and evaluation rules, 8-7 
EXTEND phrase 
in OPEN statement, 9~75, 9-76 
in USE statement, 9-152 
extended function 
DIV, 8-8 
FORMATTED-SIZE, 8-9 
MOD, 8-10 
OFFSET, 8-12 
REM, 8-12 
external devices, specifying character code 
set, 7-16 
EXTERNAL phrase, in USE statement, 
9-155 
external switches, 5-7 


F 


family substitution, linking libraries correctly, 
15-17 
family-name, as a user-defined word, 2—12 
FD, (See file-description (FD) entry) 
FEDLEVEL compiler control option, 17-22 
in libraries, 15-1 
value of, 4—2 
fields, (See data-description entry) 
figurative constants, 2-4 
collating sequence 
character associated with, 2-6 
highest ordinal position of, 5-8 
lowest ordinal position of, 5-8 
comparing alphanumeric with numeric, 2-7 
definition, 2-5 
Kanji data items 
actual character used, 2-8 
when comparing with, 7-45 
moving, 9-69 
overview, 2—4 
replacing or tallying pacers 9-54, 9-57 
rules for strings, 2-5 
using . 
in DISPLAY statement, 9-44 
in STOP statement, 9-132 
in STRING statement, 9-134 
in UNSTRING statement, 9-140 
with VALUE clause, for initializing data, 
7-47 
file, 1-6, 3-1, (See also file organization) 
assigned as REMOTE, 3-2 
creating, sequential, 5-15 
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crunching, 9-28 
declaring, 7-3 
deleting records from, 9-40 
inserting in source program, with COPY 
statement, 9-37 
logical records of, 3-1 
merging, 5-24 
passed as parameter, with CALL 
statement, 9-13 
physical aspects, 3~1 
port, 3-2 
printer backup, 12-4 
sorting, 5~24 
starting processing, 9-75 
used by compiler, 17-12 
CARD, 17-13 
CODE, 17-15 
COPY library, 17-14 
ERRORS or ERRORFILE, 17-16 
input, 17-13 
LINE, 17-15 
NEWSOURCEH, 17-15 
output, 17-15 
SOURCE, 17-14 
XREFFILE, 17-16 


file access, 3-5 


dynamic 
in indexed file organization, 5-22 
in relative file organization, 5-19 
for deleting records, 9-40 
for writing records, 9-165 
in sequential file organization, 5-15 
indexed, 3-6 
random, 3-5 
in indexed file organization, 5~22 
in relative file organization, 5-19 
READ statement, 9-93 
replacing records with REWRITE 
statement, 9-109 
sequential _ 
concepts, 3-5 
for reading, 9-95 
for seeking, 9-116 
for starting, 9-130 
in relative file organization, 5-19 


file attributes: 


as event-identifiers, for CAUSE statement, 
9-19 

assigning initial values for, 7-10 

at close-file time, 9-28 

coding VALUE OF clause (example), 7-12 

- compiler file equation, 17-13 
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equating value of, 7-10 
for subfiles, 3-3 
identifiers, 3-3 
modifying 
with CHANGE statement, 9-20 
with SET statement, 9-116 
name of 
STATIONLIST, 9-21 
SYNCHRONIZE, 9-164 
overview, 3-2 
testing, 8-20 
types of 
alphanumeric, 3-4 
Boolean, 3-5 
event, 3-5 
mnemonic, 3-4 
numeric, 3-4 
. values during compilation, 17-13 
File Not Open condition for sequential I/O, 
5-28 
file organization, 3-5, (See also file) 
default, 5-15 
indexed, 3-6, (See also indexed file 
organization) 
relative, 3-5, (See also relative file 
organization) 
sequential, 3-5, (See also sequential file 
organization) 
FILE SECTION 
function, 7-3 
in Report Writer, 12-1 
overview, 7-1 
rules for using VALUE clause with, 7-49 
FILE STATUS clause, (See status 
reporting) 
indexed I/O, 5-24 
relative I/O, 5-19 
sequential, 5-27 
sequential I/O, 5-16 
FILE-CONTROL paragraph, 5-12 
file-description (FD) entry, 7-3 
location in source program, 1-6 
file-name, as a user-defined word, 2~12 
FILLER keyword, 7-19 
implicit with SYNCHRONIZED clause, 
7-39 
FIRST DETAIL phrase 
in PAGE clause, 12—7 . : 
in report-description (RD) entry, 12-3 
fixed insertion editing, (See editing) 
floating insertion editing, (See editing) 
floating-point format 
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internal, with real or double data items, 
7-44 | 
floating-point literals, 2-16, (See also 
literals) 
exponent of, 2-16. 
mantissa of, 2—16 
value of, 2-16 
footing 
' in LINAGE clause, 7-15 
in Report Writer, 12-18 
FOOTING phrase 
in file-description (FD) entry, 7-14 
in PAGE clause, 12-7 
in report-description (RD) entry, 12-3 


Form Not Found condition, for sequential I/O, 


5-29 
formal parameters, passing lower-bound, 
7-23 
format 
of source program, 1-5 
format notation, A—1 
‘braces (example), A-3 
brackets (example), A-3 
comma, A-2 
ellipses (example), A-3 
general, A-1 
letters appended to terms, A-2 
level-numbers in, A-2 
numbered, A-1 — 
period, A-2 
repeated items, A~2 
semicolon, A-2 
space, A-2 
format record, 9-168 
format template 
obtaining from convention, 16-81 
formation rules, for arithmetic expressions, 
8-7 
formats 
of records (example), 6-5 
of statements, 8-26 
FORMATTED-SIZE function, 8-9 
formlibrary 
data-description entry for, 7-19 
status values for, 5-29 
FORTRAN, passing array parameters, 7~23 
FREE compiler control option, 17-22 
debugging line cotsijeralions: 11-1 
function 
DIV, 8-8 
extended, 8-8 
FORMATTED-SIZE, 8-9 
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in DCILIBRARY, 14-1 
MOD, 8-10 
numeric, 8-8. 
OFFSET, 8-12 
RANDOM in GENERALSUPPORT 
system library, 15-17 
REM, 8-12 
function-name, in libraries, 15-7 


G 


general format notation, (See format 
notation) 
GENERALSUPPORT system library, using 
RANDOM function in, 15-17 
GENERATE statement 
in Report Writer, 12-30 
saving of control data, 12-6 
GET_CS_MSG procedure, 16-86 
GIVING phrase —. 
calling libraries, 15-6 
in ADD statement, 9-4 
in CALL statement, 15-8 
in DIVIDE statement, 9-45 
in MULTIPLY statement, 9-74 
in SUBTRACT statement, 9-136 
in WAIT statement, 9-158 
global arrays, 7-21 . 
GLOBAL clause 
definition, 7-21 
in data-description entry, 7-21 
indexed I/O, 5-21 
relative I/O, 5-18, 5-21 
sequential I/O, 5-14 
GLOBAL compiler control option, 17-23 
and GLOBAL clause, 5-14 
using (example), 7-21 
global parameters, declaring 
for indexed files, 5-21 
for relative files, 5-18 
for sequential files, 5-14 
global variables, 7-21 
overriding OWN variables, 7-28 
GLOBALTEMP compiler control option, 
17-24 
GO TO statement 
altering a label location, 9-7 
syntax, 9-51 
with PERFORM statement, 9~85 
greater than or equal to sign, 8-15 
greater than sign (>) 
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in format notation, A-3 
in relation condition, 8-15 
reserved word for, 2-10 
GROUP INDICATE clause 
in Report Writer, 12-24 
GROUP INDICATE clause, in Report Writer, 
12-22 
group item 
coding of (example), 6-3 
definition, 6-2 
in tables, 7-24 
initializing with VALUE clause, 7-48 
searching and replacing, 9-54, 9-55, 9-57 
groups 
of elementary items, 6-2 
using level-numbers, 6-3 


H 


HEADING phrase 
in PAGE clause, 12~7 
in report-description (RD) entry, 12-3 
hexadecimal digits, 2-17 
HIGH-VALUE figurative constants, 2-6, 
(See also figurative constants) 
host file, 17-35 
using GLOBAL clause, 5-14 
host program 
identifying program to be bound into, » 
9-156 
parameters for (table), 9-16 
using GLOBAL clause, 7-21 
hyphen (-) 
for continuation line, 1-10 
in system-name, 2-12 


I-O phrase 
in OPEN statement, 9-75, 9-76 
in USE statement, 9-152 
I-O-CONTROL paragraph, 5-25 
I/O areas . 
in indexed file organization, 5-22 
in relative file organization, 5-18 
in sequential file organization, 5-15 
I/O exception handling, 9-152 
I/O files, closing, 9-29 
VO ere 5-27, (See also status reporting) 
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indexed I/O, 5-31 
relative I/O, 5-30 
sequential I/O, 5-27 
T/O subsystem 
adjusting size of physical record, 7~7 
replacing records, 9-109 
role in writing records with sequential 
access, 9-165 
ID DIVISION, (See IDENTIFICATION 
DIVISION) 
identification area of area B, 1-6 
IDENTIFICATION DIVISION, 4-1 
coding (example), 4-2 
in libraries, 15-1 
overview, 1-2 
identifiers 
file attributes, 3-2 
in arithmetic expressions, 8-6 
in tasking or bound-procedure 
environment, 8-1 
multiple, assigning single value to, 9-35 
of table elements, 6-13 
resultant, 8-25 
rules for uniqueness, 6-7 
IF statement, 9-52 
as conditional expression, 8-13 
with undigit literals, 2-17 
immediate compiler control options, 17-9 
imperative statements and sentences, 8-5 
with IF statement, 9-52 
implementor-name 
definition, 2-12 
in SPECIAL-NAMES paragraph, 5-10 
indentation of source program, 1-6 
independent processes, creating, 9-111 


index data item 


comparing with index-name, 8-17 
definition, 7-45 
in RENAMES clause, 7-50 
in Report Writer, 12-6 
in SEARCH statement, 9-112 
in SET statement, 9-118 
in table handling, 6-15 
in USAGE clause, 7-44 
INDEX phrase 
in data-description entry, 7-18 
in USAGE clause, 7-42, 7-45 
index-names 
as a user-defined word, 2-12 
comparing, 8-17 
INDEXED BY clause 
with SEARCH statement, 9-112, 9-114 
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with SET statement, 9-119 
indexed file organization, 5-21 
concepts, 3-6 
creating localized, 16-9 
declaring, 5-21 
deleting records, 9-40 
localized, creating, 16-16 
random access for, 9~96 
starting sequential access with, 9-130 
writing records with, 9-166 
indexed I/O, 3-6 
close file actions, 9-30 
current-record pointer, 3-6 
I/O status, 5-31 
of the FILE-CONTROL paragraph, 5—21 
when opening a file, 9-75 
INDEXED phrase 
in communication-description (CD) entry, 
14-12 
in OCCURS clause, 7-25 
indexing, of tables, 6-14 
indicator area, in source program, 1-6 
INERROR parameter of SEQCHECK 
compiler control option, 17-35 
INFO compiler control option, 17-25 
INITIAL clause, in COMMUNICATION 
SECTION, 14-7 
INITIAL INPUT clause, 14~7 
initial state of a library, 15-8 
initializing data items with VALUE clause, 
7-46 
INITIATE statement 
in Report Writer, 12-29 
PAGE-COUNTER special saa 12-11 
input files 
-closing, 9-29 . 
OPTIONAL phrase with, 5-15 
used by compiler 
CARD, 17-138 
COPY library, 17-14 
SOURCE, 17-14 
INPUT phrase 
in communication-description (CD) entry, 
14-7 
in OPEN statement, 9-75 
in USE statement, 9-152, 


INPUT PROCEDURE, in SORT statement, 


9-122 
INPUT TERMINAL phrase 
in DISABLE statement, 14—20 
in ENABLE statement, 14—21 
input text 
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collating, 16—105 
obtaining ordering information for, 16-105 
INPUT-OUTPUT SECTION, 5-11 
overriding file attribute values of, 7-10 
inserting files in source program with COPY 
statement, 9-37 
insertion editing, (See editing) 
INSPECT statement, 9-53 
rules for replacing characters, 9-55 
rules for tallying, 9-54 
using (examples), 9-60 
with undigit literals, 2-18 
INSTALLATION paragraph, 4—1 
INTEGER phrase, for calling libraries, 15-6 
Inter-Program Communication (IPC), 9-18, 
13-1 
ending called program, 13-6 
ending run unit, 13-7 
EXIT PROGRAM statement, 13-6 
initializing called program, 13-5 
mechanism, 9-132 
naming parameters, 13-3 - 
required data clauses, 13-3 
restriction, 7-35 
scope of data items, 13-2 
subset of libraries, 15-1 
syntax of 
CALL statement, 13-4 
DATA DIVISION, 13-1 
EXIT PROGRAM statement, 13-6 
LINKAGE SECTION, 13-1 
PROCEDURE DIVISION, 13-3 
STOP statement, 13-7 
transferring control in run unit, 13-4 
internal representation of data items, 7-44 
when moving, 9-69 
internationalization, 16-1 
ACCEPT statement, 9-2 
CCSVERSION phrase, 5-8 
CENTRALSUPPORT library procedures 
functions of (table), 16-21, 16-23 
COMPARISON clause, 5-22 
CONVENTION phrase, 7-39 
default settings, changing, 16-3 
hierarchy, 16-3 
KEY-LENGTH clause, 5-23 
LANGUAGE phrase, 7-39 
move rules, 9-70 
PROGRAM COLLATING cok See 
clause, 5-4 
TYPE clause, 7-39 
interrupt 
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with ALLOW statement, 9-5 
with ATTACH statement, 9-7 
with CAUSE statement, 9-19 
with DETACH statement, 9-41 
with DISALLOW statement, 9-42 
with USE statement, 9-157 
with WAIT statement, 9-160 
INVALID INDEX error 
with CALL statement, 9-14 
with PERFORM statement, 9-85 
with SORT statement, 9-125, 9-127 
with tables, 6-13 
Invalid Key condition, 5-27 | 
for indexed I/O, 5-82 
for relative I/O, 5-30 
for sequential I/O, 5-27 
in DELETE statement, 9-40 
in READ statement, 9-96 
in REWRITE statement, 9-108, 9-110 
in START statement, 9-131 
in WRITE statement, 9-163, 9-166 
when deleting records, 9-40 
IPC, (See Inter-Program Communication 
— (PC)) 
iteration, (See PERFORM statement) 


J 


JUST clause, (See JUSTIFIED clause) 
justification 
' of elementary items, 7-22 
when moving data, 9-70 
with data alignment, 6-10 — 
with RENAMES clause, 7-51 
with SYNCHRONIZED clause, 7-39 
JUSTIFIED clause 
general format, 7-22 
in data-description entry, 7-22 
_ in Report Writer, 12-22 
_ with initialization process, 7-48 


K 


Kanji 


characters, figurative constants with, 2-8 


data alignment, 6-10 
data items 
defining, 7-31 
figurative constants with, 7-45 
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internal representation of, 7-45 
moving, 9-69 
types of, 6-5 
with VALUE clause, 7-48 
writing of, 9-167 
FORMATTED-SIZE function, 8-9 
literals, definition, 2-18 
operands, comparing, 8-17 
KANJI phrase in USAGE clause, 7-42 
Kanji-edited data items 
defining, 7-31 
types of, 6-5 
KEY IS phrase, 7-26, 7-27 
KEY phrase 
in DISABLE statement, 14-20 
in ENABLE statement, 14-21 
in START statement, 9-130 
KEY-LENGTH clause, 5-23 
KEYEDIOI[, creating localized indexed file, 
16-16 
keys 
for file access in indexed I/O 
with alternate keys, 5-23 
with duplicate keys, 5-23 
with primary key, 5-22 
for writing records, 9-165 
in indexed files, 3-6 
in tables 
for data in ascending or descending 
order, 7-26, 7-27 
rules for when merging files, 9-66 
sorting on, 9-123 
using START statement with, 9-131 
keywords © 
overview, 2-8 
types of, 2-8 
using (example), 2-9 
when required, A-2 


L 


LABEL clause, in file-description (FD) entry, 
7-8 
LABEL RECORDS clause, 7-8 
language, 16-1 
name, obtaining, 16-28 
run-time, establishing, 16—4 
system default, obtaining name of, 16-37 
language elements, 2~1 
LANGUAGE phrase, 7-39 
LANGUAGE task attribute, 16-4 
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languages 
available, obtaining names of, 16-90 
bound, obtaining names of, 16-90 
_LAST DETAIL phrase 
in PAGE clause, 12-7 
in report-description (RD) entry, 12-3 
LD, (See local-storage description (LD) 
entry) 
LEADING phrase, in INSPECT statement, 
9-54 
less than or equal to sign, 8-15 
less than sign (<) 
in format notation, A-3 
in relation condition, 8-15 
reserved word for, 2~10 
LEVEL compiler control option, 17-26 
level indicators (FD, SD), 1-6, (See also 
file-description (FD) entry, sort 
merge description (SD) entry) 
for record descriptions, 7-17 
location in source program, 1-6 
level-number, 7-19 
as a user-defined word, 2-12 
in format notation, A~2 
in record description (example), 6-5 
indentation of, 1-9 
numbering of, 6-3 
organization as a system, 6-2 
rules for LEVEL-NUMBER clause, 6-4 
uniqueness of, 2—12. 
level-number 01, definition, 6-4 
level-number 66, definition, 6-4 
level-number 77, definition, 6-4 
level-number 88, definition, 6-4 
lexicographic 
level 3 
for EXIT PROCEDURE statement, 
9-49 
to use global variables, 7-21 
to use local variables, 7-23 
setting levels, 17-26 
02-level 
for creating independent processes, 
9-111 
LIB§ compiler control option, 17-26 


LIBDOLLAR compiler control option, 17-26 


. LIBERATE function of operating system 
with LOCK statement, 9-63 
with UNLOCK statement, 9-139 
libraries, 15-1, (See also COPY statement) 
attributes 
changing, 15-13 
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types of, 15-12 
calling ALGOL typed procedure, 15-8 
compiler control options 
LIBRARYLOCK, 15-14 
permanent, 15-15 
sharing, 15-5, 17-38 
SHARING, 15-14 
TEMPORARY, 15-15 
creating, 15-1 
data integrity, 15-5 
ensuring with LIBRARYLOCK option, 
17-26 
DCILIBRARY, 14-1 
ending 
by transferring control to calling 
program, 15-4 
library and calling program, 15-4 
with CANCEL statement, 15-10 
function-name, 15-7 
initial state, 15-8 
initializing called program, 15-10 
parameters, 15-3 
for library calls, 15-7 
performance considerations, 15-7, 15-11 
permanent, initial state of, 15-9 
program 
controlling family assignment in, 15-17 
creating temporary, 15-15 
creating temporary or permanent, 
17-43 
ending with STOP RUN statement, 
9-132 
returning from calling program, 15-4 
returning with EXIT PROGRAM 
statement, 9-35 
recursive calls, 15-5 
restriction, 7-35 
syntax of 
CALL statement, 15-6 
CANCEL statement, 13-5, 15-10 
CHANGE ATTRIBUTE statement, 
15-13 
EXIT PROGRAM statement, 15-4 
PROCEDURE DIVISION statement, 
15-1 
temporary, initial state of, 15-9 
using 
calling (examples), 15-16 
calling entry points, 9-15 
compiler control records in, 17-26 
declaration, 15-6 
declaration qualification, 6-9 
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matching parameters when calling, 15-6 
syntax for calling, 15-5 . 
written in other languages, 15-8 
library-name, as a user-defined word, 2-12 
library-title, 15—7 
LIBRARYLOCK compiler control option, 
17-26 
LINAGE clause, 7-14 
in file-description (FD) entry, 7-14 
when writing to files, 9-162 
LINAGE-COUNTER, 7-15 
special register for LINAGE clause, 2-9 
LINE compiler control option 
use during compilation, 17-15 
LINE file, used by compiler, 17-15 
line layout, 1-5 
LINE NUMBER clause, in Report Writer, 
12-13, 12-14 
LINE-COUNTER | 
function in Report Writer, 12-12 
register for Report Writer, 2-9 
LINEINFO compiler control option, 17-27 
LINES AT BOTTOM phrase, in 
. file-description (FD) entry, 7-14 
LINES AT TOP phrase, in file-description 
(FD) entry, 7-14 | 
LINES clause, in file-description (FD) entry, 
7—4 
lines per page 
in convention, determining, 16-61 
specifying with LINAGE clause, 7-14 
linkage records in Inter-Program | 
Communication (IPC), 138-3 
LINKAGE SECTION 
for defining PROCEDURE DIVISION 
- parameters, 8-1 
in Inter-Program Communication (IPC), 
. 13-1 : 
overview, 7-1 
rules for using VALUE clause in, 7-49 
linkage storage, noncontiguous in IPC, 13-2 
LIST compiler control option, 17-27 
LIST$ or LISTDOLLAR compiler control 
option, 17-27 
LISTDELETED compiler control option, 
17-28 
LISTOMITTED compiler control option, 
17-28 
LISTP compiler control option, 17-28 
LIST 1 compiler control option, 17-28 
literals | 
as character strings, 2-3 
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definition, 2-14 
floating-point (examples), 2-17 
in arithmetic expressions, 8-6 
in format notation, A-2 
in relation conditions, 8-14 
Kanji, 2-18 
moving, 9-69 
nonnumeric 
character set for, 2-1 
definition, 2-14 
punctuation for, 2-3 
numeric (examples), 2-14 
rules with VALUE clause, 7-47 
undigit, 2-17 
use in changing attributes, 9-21 
with figurative constants, 2-7 
LOCAL clause 
in data-description entry, 7-23 
indexed I/O, 5-21 . 
relative I/O, 5-18 
sequential I/O, 5-14 
syntax, 7-23 
local parameters, declaring 
for indexed files, 5-21 
for relative files, 5-18 
for sequential files, 5-14 
local variables 
definition, 7-23 
overriding OWN variables, 7-28 
local-storage description (LD) entry, 7-54 
LOCAL-STORAGE SECTION 
overview, 7-1 
syntax, 7-54 
localization, 16-1 
establishing conventions for, 16-4 
procedures, 16-30 
lock file disposition, sequential I/O, 9-28 
LOCK phrase 
in CLOSE statement 
for multiple-reel tapes, 9-26 
for nonreel files, 9-24 
for relative or indexed I/O, 9-30 
for single-reel files, 9-25 
in data-description entry, 7-18 © 
in MERGE statement, 9-64 
in OPEN statement, 9-77 
in SORT statement, 9-122 
in USAGE clause, 7-42 
LOCK statement, 9-62 
logic of program, (See program logic) 
logical connectives, 2-5 
logical operators, 8-21 
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combinations of (table), 8-22 
logical page size, definition, 7-14 
logical records, 8-1, (See also records) 
errors 
with indexed I/O, 5-32 
with relative I/O, 5-30 
with sequential I/O, 5-28 
implicitly redefining, 9-93 
of variable length, 7~8 
reading, 9-93 
relationship to physical records, 7-6 
rules for when merging files, 9~65 
rules.when sorting files, 9-126 
using OFFSET function, 8-12 
writing, 9-160 
LONG-DATE type, 16-16 
LONG-TIME type, 16-16 
looping, with PERFORM statement, 9-83 
LOW-VALUE figurative constants, 2-6, (See 
also figurative constants) 
LOW-VALUES figurative constants, 2-6, 
(See also figurative constants) 
LOWER-BOUNDS clause 
coding of (example), 7—24 
in COBOL68 parameter mapping, 9-14 
' in data-description entry, 7-23 
"in linkage records, 13-3 
syntax, 7-23 


MAKEHOST compiler control option, 17-29 
mantissa, definition, 2-16 
MAP compiler control option, 17-29 
during compilation, 17-15 
mapping of parameters for tasking calls, 9-14 
mapping table, 16-6 
. using to modify text, 16-113 
margins, in file-description (FD) entry, 7-14 
Master Control Program (MCP), (See 
operating system) 
mathematics, (See arithmetic) 
maximum number 
of characters allowed in PICTURE 
character string, 7-29 
of errors before compilation ends, 17-21 
of nesting levels for procedures, 9-85 
maximum size 
of arithmetic operands, 8-26 
of dimensions in table, 6-11 
of record description, 6-1 
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of record when using RECORD 
CONTAINS..DEPENDING ON 
clause, 7-8 
of segment, 10-1 
of table subscript value, 6-13 
MCP_BOUND_LANGUAGES procedure, 
16-90 
MCS (message control system), 14-1 
memory 
allocation of, when sorting files, 9-124 
occupied by 
binary data items, 7—42 
double data items, 7-44 
real data items, 7-44 
redefining, 7—35 
with multiple 01-level entries, 7~19 
releasing for libraries, 15-10 
sharing 
in sequential I/O, 3-5 
specifying, 5-25 
MEMORY SIZE clause, 5-3 
in MERGE statement, 9-64 
in OBJECT-COMPUTER paragraph, 5-3 
in SORT statement, 9-122, 9-124 
MERGE compiler control option, 17-30 
use during compilation, 17-14 
MERGE phrase, in SELECT clause, 5-24 
MERGE statement 
closing, 9-27 
ending of, 9-67 
function and syntax, 9-64 
in localized application, 16-17 
placement in source, 9-65 
rules for keys, 9-66 
when equating file attributes, 7-11 
merging files, 9-64 
' effect of coded character set, 16-9 
identifying in FILE-CONTROL paragraph, 
5-24 . 
using RETURN statement to obtain 
records, 9-106 
message control system (MCS), 14-1 
MESSAGE COUNT phrase, 14-7 
MESSAGE DATE phrase, in 
communication-description (CD) 
entry, 14-7 


MESSAGE phrase, in RECEIVE statement, 


14-23, 14-24 

MESSAGE TIME phrase, in 
communication-description (CD) | 
entry, 14-7 


8600 0296-000 


Message Translation Utility (MSGTRANS), 
16-10 
messages 
creating in MLS environment, 16-10 
displaying in different languages, 16-86 
FILLER ADDED, 6-2 
input, 16-10 
obtaining text associated with number, 
16-86 
output, 16-10 
‘routing, (See message control system 
(MCS)) 
warnings 
suppressing printing of, 17-39, 17-45 
treating like syntax errors, 17-45 
minus sign (—) 
for editing sign-control, 6-18 
in arithmetic expression, 8-6 
in format notation, A-3 
with fixed insertion editing, 6-20 
MLS (MultiLingual System), 16-1 
mnemonic 
attributes in CHANGE statement, 9-21, 
9-22 . 
file-attribute identifiers, 3-4 
task-attribute identifiers, 3-8 
mnemonic-name 
as implementor-name, 2-13 
as user-defined word, 2-14 
MOD function, 8-10 
modulus, using MOD function for modulus 
division, 8-10 . 
monetary symbols in convention, listing, 
16-67 
monetary value 
formatting, 16-41 
formatting to edited monetary value, 
16-44 
MOVE ALL construct, using (example), 2-7 
MOVE statement 
elementary moves, 9-68 
file attributes in, 3-4 
for partial words (examples), 9-72 
implicit in READ statement, 9-95, 9-97, 
9-98, 9-100 
in localized applications, 16-17 
nonelementary moves, 9-70 
syntax and function, 9-68 
types of (table), 9-71 | 
using numeric functions with, 8-8 
using task attributes with, 3-8 
with CORRESPONDING phrase, 8-26 
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with undigit literals, 2-17 
‘with USAGE clause, 7-45 
MSGTRANS, (See Message Translation 
Utility (MSGTRANS)) 
MultiLingual System (MLS), 16-1 
multiple fields, creating from contiguous data, 
9-139 
MULTIPLE FILE clause, 5-26 
MULTIPLE FILE TAPE CONTAINS clause, 
in I-O-CONTROL paragraph, 5—26 
multiple-file reel 
location of files on, 5—25 
reading and writing to, 5-26 
when merging files, 9-65 
multiple-file tape, closing, 9-25 
multiple-reel tapes, closing, 9-26 
multiplication, 2-10 
arithmetic symbol for, 8-6 
MULTIPLY statement, 9-73, (See also 
multiplication) 
storing results in multiple fields, 8-27 
MYJOB reserved word 
in SET statement, 9-120 
task item, 3-7 
MYSELF reserved word 
in SET statement, 9-120 
task item, 3—7 


NATIVE clause, in SPECIAL-NAMES 
paragraph, 5-7 
natural language, 16-1, 16-10 
formatting data items for, 16-16 
negated simple conditions, 8-21 
negative value 
operational sign for, 7-38 
truth test for, 8-20 
nesting of procedures, 9-85 
NETWORK option of RESERVE clause, 5-10 
NEW compiler control option, 17-30 
- use during compilation, 17-15 
NEWID compiler control option, 17-31 
NEWSOURCE file, used by compiler, 17-15 
NEXT GROUP clause, in Report Writer, 
12-13, 12-15 
NEXT PAGE clause, in NEXT GROUP 
clause, 12-15 _— 
NEXT SENTENCE phrase 
with IF statement, 9-52 
with LOCK statement, 9-62 
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with SEARCH statement, 9-111 in arithmetic expressions, 8— 


no buffer condition, with sequential I/O, 5-29 rules for, 2-15 
no data condition, with sequential I/O, 5-29 operands, comparing, 8-16 
NO DATA phrase, in RECEIVE statement, symbols in convention, listing, 16-67 
14-23 NUMERIC identifier, 8-18 
No Record Found condition NUMERIC-DATE type, 16-16 
for indexed I/O, 5-82 numeric-edited data items 
for relative I/O, 5-30 rules for, 7-30 
no rewind of current reel disposition, 9-28 types of, 6-5 
NO REWIND phrase NUMERIC-TIME type, 16-16 
in CLOSE statement 
for multiple-reel tapes, 9-26 
for single-reel files, 9-25 O 
in MERGE statement, 9-64 
in OPEN statement, 9-75, 9-76, 9-77 object code, listing of, 17-19 
in SORT statement, 9-122 object files, 17-12 
NO WAIT phrase object of condition, 8-15 
in AWAIT-OPEN statement, 9-9 object program 
in CLOSE statement, 9-31 stopping, 9-132 
in OPEN statement, 9-76, 9-77, 9-80. suspending, 9—157 
in READ statement, 9-94 using COPY statement to replace source 
in WRITE statement, 9-163 . text in, 9-38 
noncontiguous working-storage items, 7-53 OBJECT-COMPUTER paragraph, 5-3 
nonnegative value, operation sign for, 7-38 object-time switch, in debug module, 11-1 
nonnumeric literals OC clause, (See OCCURS clause) 
character set for, 2-1, (See also literals) OCCURS clause, 3-7 
definition, 2-14 | in data-description entry, 7-24 
in continuation line, 1-11 overview of tables, 6-11 
punctuation for, 2-3 : tables, 7-25 
using quotation marks (example), 2-14 task attributes with, 3-7 
nonnumeric operands, comparing, 8-16 with ASCENDING KEY phrase, 7-25 
nonreel file, 9-23 with CORRESPONDING phrase, 8-26 
nonserial search operation, 9-115 with DEPENDING ON phrase, 7-26 
normal termination, 9~132 with DESCENDING KEY phrase, 7-25 
NOT logical operator with SEARCH statement, 9-112, 9-114 
in abbreviated combined conditions, 8-23 ODT (operator display terminal), 5-7 
in relation condition, 8—15 ODT commands, (See system commands) 
meaning of, 8-21 -ODT-INPUT-PRESENT phrase, in WAIT 
notation used in general formats, (See _ Statement, 9-158 
format notation) | ' OFF STATUS clause, in SPECIAL-NAMES 
NOXREFLIST compiler control option, 17-31 paragraph, 5-7 
numbered format notation, A~1 OFFER phrase, in OPEN statement, 9-76, 
numeric 9-77, 9-80 
data OFFSET (data-name) function, 8-12 
defining as, 7-30 OMIT compiler control option, 17-32 
types of, 6-5 ON DISK phrase, in I-O-CONTROL 
using SIGN clause with, 7-37 paragraph, 5-25 
display, international formatting, 16-14 ON ERROR phrase 
file-attribute identifier, 3-4 in MERGE statement, 9-64, 9-65 
function, 8-8 in SORT statement, 9-122, 9-123 
hexadecimal digits, 2-17 ON NEXT PAGE phrase, in Report Writer, - 
literal 12-21 : 
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ON OVERFLOW phrase 
calling libraries, 15-6 
in STRING statement, 9-133, 9-136 
in UNSTRING statement, 9-140, 9-143, 
9-146 
ON SIZE ERROR phrase 
in ADD statement, 9-3 
in COMPUTE statement, 9-34 
in DIVIDE statement, 9-45, 9-47 
in MULTIPLY statement, 9-74 
in SUBTRACT statement, 9-186 


ON STATUS clause, in SPECIAL-NAMES 


paragraph, 5-7 
open modes, 9-78 
OPEN statement, 9-75, (See also opening a 
file) 
after crunching a file, 9-28 
current-record pointer, 3-6 
function and syntax, 9-75 
reopening of a file, 9-77 
specifying number of line on logical page, 
7-14 
when deleting records, 9-40 
when equating file attributes, 7-11 
when status values are updated 
for indexed I/O, 5-31 
for relative I/O, 5-30 
for sequential I/O, 5~27 
when using port files, 3-2, 7-12 
with multiple-file tapes, 5-26 
opening a file, 7-14 
automatically when merging files, 9-65 
status errors, 5-27 
- with more than one file on a reel, 5-26 
operands 
comparing, 8-16 
overlapping, 9-5 
validity in SET statement, 9-118 
operating system 
automatic file allocation, 7-8 
controlling sharing of libraries, 17-38 
dump, 9-18 
passing control to, 9-18 
PROCURE and LIBERATE functions, 
9-63 
role in DISPLAY statement, 9-44 
role in passing lower-bound parameters, 
7-23 
status of execution 
for indexed files, 5-24 
for relative files, 5-19 
for sequential files, 5-16 
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operator display terminal (ODT) 
and SPECIAL-NAMES paragraph, 5-7 
transferring data to, 9-43 
using ACCEPT statement, 9-1 
using AX (accept) command, 9-159 
using SL (Support Library) command for 
library linking, 15-17 
operators 
arithmetic 
combining, 8-7 
definition, 8-6 
reserved words for, 2-10 
separating identifiers in expressions, 
8-6 
logical 
combining, 8-21 
definition, 8-20 
relational 
definition, 8-15 
reserved words for, 2-10 
with Kanji operands, 8~17 
OPT or OPTIMIZE compiler control option, 
17-32 
optimizing code for a machine, 17-42 
option action indicators, 17-10 
OPTION task attribute, 11-1 
(example), 3-9 
optional file, closing, 9-28 
OPTIONAL phrase, 5-15 
in SELECT clause, 5-13 
optional words 
definition, 2-8 
overview, 2-8 
options, 1-5 
OR logical operator 
in abbreviated combined conditions, 8-23 
meaning of, 8-21 
ordering of input text, 16-105 
ORGANIZATION clause 
indexed I/O, 5-22 
relative I/O, 5-19 
sequential I/O, 5-15 
ORGANIZATION IS INDEXED phrase, in 
SELECT clause, 5-15 
ORGANIZATION IS RELATIVE phrase, in 
SELECT clause, 5-17 
ORGANIZATION IS SEQUENTIAL phrase, 
in SELECT clause, 5-13 
OUTERROR parameter of SEQCHECK 
compiler control option, 17-35 
output files 
closing, 9-29 
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from merge process, 9-64 
from sort process, 9-121 
- logical page size of, 7-14 
specifying lines per page 
with LINAGE clause, 7-14 
used by compiler 
CODE, 17-15 
ERRORS, 17-16 
ERRORS or ERRORFILE, 17-16 
LINE, 17-15 
NEWSOURCEH, 17-15 
output message array, use in localization, 
16-10 
output mode 
no current-record pointer with, 3-6 
writing a file in, 9-165 
OUTPUT phrase 
in communication-description (CD) entry, 
14-12 
in OPEN statement, 9-75 
in USE statement, 9-152 
OUTPUT PROCEDURE 
in SORT statement, 9-122, 9-126 
when merging files, 9-67 
output record, 9-168 
synchronized, 9-164 
OUTPUT TERMINAL phrase 
in DISABLE statement, 14-20 
in ENABLE statement, 14-21, 14-22 
OVERFLOW phrase 
in STRING statement, 9-133, 9-136 
in UNSTRING statement, 9-140, 9-143, 
9-146 
with SYNCHRONIZED clause, 7-39 
overlapping operands 
ADD statement, 9-5 
COMPUTE statement, 9-35 
DIVIDE statement, 9-47 
INSPECT statement, 9-53 
MOVE statement, 9-68 
MULTIPLY statement, 9-75 
SET statement, 9-117 
STRING statement, 9-134 
SUBTRACT statement, 9-138 
UNSTRING statement, 9-139 
OWN clause, general format of, 7-28 
OWN compiler control option, 17-33 
relation to OWN clause, 7-28 
OWNTEMP compiler control option, 17-34 
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P edit character in PICTURE clause, 6-16 
with ROUNDED phrase, 8-25 
page advance ~ 
control with WRITE statement, 9-162 
LINAGE-COUNTER value, 7-15 
page body, definition, 7-14 
PAGE clause 
in report-description (RD) entry, 12-3, 
12-7, 12-10 
in SEND statement, 14-29 
in WRITE statement, 9-162 
PAGE compiler control option, 17-34 
page ejection, of source listing, 1-10 
PAGE FOOTING phrase, in Report Waiter 
12-13, 12-16 
defining, 12-9 
function of, 12-18 
page format control 
with LINAGE clause, 7—14 
with Report Writer, 12-10 
PAGE HEADING phrase, in Report Writer 
defining, 12-8 
function, 12-17 
in TYPE clause, 12-16 
syntax, 12-13 
page overflow, when executing WRITE 
statement, 9-163 
PAGE-COUNTER 
function in Report Writer, 12~11 
register for Report Writer, 2-10 
page, defining logical page size of, 7-14 
page, defining logical size of, 7-14 
paragraph headers, in source program, 1-6 
paragraph-name 
as user-defined word, 2—18, 2—14 
qualification of, 6~7 
paragraphs, 1-3, 8-3 
parameters | 
by-content 
specifying, 7-34 
by-reference 
in relative file organization, 5-18 
in sequential file organization, 5-14 
specifying, 7-34 
by-value 
specifying, 7-34 
using, 1-24 
for bound and host programs, 9-16 
for libraries, 15-3 
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formal, when starting independent 
processes, 9-110 
global, declaring 
for indexed files, 5-21 
for relative files, 5-18 
for sequential files, 5-14 
using, 7~21 
in communication module, 14-1 
local, declaring 
for indexed files, 5-21 
for relative files, 5-18 
for sequential files, 5-14 
using, 7-23 
mapping for tasking calls, 9-14 
matching between languages (table), 9-14 
matching when calling libraries, 15-6 


passing lower-bound parameter (example), 


7-23 
receiving lower-bound parameter, 15-4 
to called libraries, 15-7 
types of, for CALL statement, 9-13 
using local-storage description (LD) entry, 
7-54 
parentheses 
as separator, 2-2 
for precedence 
in arithmetic expressions, 8-7 
in conditional expressions, 8-22 
parity errors 
‘for indexed I/O, 5-32 
for relative I/O, 5-30 _ 
for sequential I/O, 5-27, 5-28 
when merging files, 9-65 
when sorting files, 9-123 
partial words 
excluded in pseudotext, 9-38 


manipulating with MOVE statement, 9-72 


PARTICIPATE phrase, in AWAIT-OPEN 
statement, 9-9 
password, in communication module, 14-3 
pausing, with STOP statement, 9-132 
PB (Printer Backup) WFL statement, 12-5 
PC clause, (See PICTURE clause) 
PERFORM statement 
analysis with OPTIMIZE compiler control 
option, 17-33 
as conditional expression, 8-13 
exiting from, 9-50 
function and syntax, 9-83 
PERFORM...TIMES form, 9-86 
PERFORM...UNTIL form, 9-87 
PERFORM...VARYING form, 9-88 
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simple form, 9-84 
with undigit literals, 2-17 
performance considerations in libraries, 15-7, 
15-11 
period (.) | 
as edit character in PICTURE clause, (See 
decimal point) 
as separator, 2-2 
using 
in CHANGE statement, 9-21 
in compiler-directing statements, 8-5 
in COPY statement, 9-37 
in format notation, A-2 
in paragraphs and sentences, 1-3, 8-3 
peripherals, changing, 14-1 
permanent error condition, 5-27 
Permanent Error condition 
for indexed I/O, 5-32 
for relative I/O, 5-30 
for sequential I/O, 5-27 
permanent files 
closing, with sequential file organization, 
9-28 
in save file with remove disposition, 9-29 
permanent libraries, 15-15 
- initial state of, 15-9 
PF phrase, (See PAGE FOOTING phrase, in 
Report Writer) 
PH phrase, (See PAGE HEADING phrase, 
in Report Writer) 
physical files, during compilation, 17-13 
physical records, 6-1, (See also records) 
containing variable-length logical records, 
7-6 
specifying size, 7-6 
PIC clause, (See PICTURE clause) 
PICTURE character string 
in format notation, A-2 
separator in, 2-3 
PICTURE clause, 7-29, (See also elementary 
items) 
categories of data, 7-29 
edit characters used in, 7-31 
in Report Writer, 12-22 
relation to USAGE IS BINARY 
TRUNCATED clause, 7-43 
relation to VALUE clause, 7-47 
plus sign (+) 
for editing sign-control, 6-18 
in arithmetic expression, 8-6 
in format notation, A-3 
with fixed insertion editing, 6-20 
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POINTER phrase 
in STRING statement, 9-133, 9-135 
in UNSTRING statement, 9-139, 9-143, 
9-145 
- POINTER task attribute, 3-8 
POP option action indicator, 17-11 
port files 
closing, 9-31 
- with ACTUAL KEY clause specified, 
9-33, 9-106 
definition, 3-2 
file attributes for, 3-3 
format of variable-length records in, 7—8 
opening, 9-79 
opening a subfile, 7-12 
reading, 9-94, 9-96 
selecting subfile index of, 5-15 
specifying a subfile, 3-3 
status errors for sequential I/O, 5-27 
suspending program, 9-158 
with AWAIT-OPEN statement, 9-9 
with sequential file organization, 5-15 
writing records to, 9-163, 9-169 
positive value, truth test for, 8-20 
precedence rules 
for arithmetic expressions, 8-7 
for comparing key data in MERGE 
statement, 9-66 
for editing, 7-32 
for evaluating conditions, 8-24 
previous reels unaffected, disposition, 9-29 
primary keys, 5-22 
when replacing records, 9-109 
printer backup files 
printing of, in Report Writer, 12-5 
title of, when CODE clause is epeaned, 
12-4 
with sequential file organization, 5-13 
printer files 
closing, 9-23 
writing to, 9-168 
printing 
LINAGE-COUNTER register, 2-9 
of comment in COPY statement in 
compilation listing, 9-39 
reports 
with LINAGE clause, 7-14 
with Report Writer, 12-2 
suppression of warning messages, 17-45 
PROCEDURE DIVISION, 8-1 
in Inter-Program Communication (IPC), 
13-3 
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in libraries, 15-1, 15-2 
in Report Writer, 12-29 
deemphasis of, 12-1 
in the debug module, 11-2 
localization syntax, 16-17 
overview, 1-2 
PROCEDURE DIVISION header 
SELECT clause with, 5-14, 5-18, 5-21 
procedure-name 
definition, 8-3 
qualification of, 6-7 
PROCEDUREDIVISION entry point, 15-1 
procedures 
altering location of label, with ALTER 
statement, 9-7 
bound , 
identifying global procedures used in, 
9-156 
passing lower-bound parameters for, 
7-23 
coroutine, with EXIT statement, 9-49 
definition, 8-3 
dissociating from task items or EVENT 
items, 9-41 
file as formal parameter for, 5-14, 5-17 
for localizing applications, 16-30 
global variables in, 7-21 
interrupt 
with ALLOW statement, 9-6 
with CAUSE statement, 9-19 
local variables in, 7-23 
local-storage description (LD) entry, 7-54 
nesting, 9-85 
OWN clause in, 7-28 
specifying parameters for, 7-34 
transferring control to 
with CALL statement, 9-12 
with PERFORM statement, 9-83 
PROCESS statement 
relationship to PROCEDURE DIVISION 
parameters, 8-1 
syntax and function, 9-92 
with DETACH statement, 9-41 
processes . 
asynchronous 
releasing a lock, 9-189 
starting, 9-92 
using CAUSE statement with, 9-19 
communication between, 3-2 
correlating activities, with USAGE clause, 
7-44 
independent, starting, 9-110 
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interrupt procedures for, 9-157 
resuming execution of, 9-35 
synchronous, transferring control to, 9-35 
task attributes of, 3-6 
PROCURE function of operating system, 
9-63 
PROGRAM COLLATING SEQUENCE 
clause 
accessing alphabetic truthset, 16-7 
in OBJECT-COMPUTER paragraph, 5-3 
in START statement, 9-131 
program control, (See branching logic) 
program example, (See example program 
for) 
program logic 
branching, 8-13 
using GO TO statement, 9-51 
using IF statement, 9-52 
looping, with PERFORM statement, 9-83 
testing 
for condition-name, 8-19 
for events, 8-20 
for negated condition, 8-21 
for numeric or alphabetic, 8-18 
for sign, 8-19 
transferring control to a task or a 
procedure, 9-12 
PROGRAM-ID clause, in libraries, 15-1 
PROGRAM-ID paragraph, 4-2 
program-name 
as user-defined word, 2-14 
for identifying source program, 4-2 
PROGRAMDUMP utility, 17-18 
programs 
_ bound as procedures, 9-16 
interrupt driven, 9-160 
protocols, data communications, 
international, 16-1 
pseudotext 
definition, 9-38 
delimiters for, 2~2 
punch files, closing, 9-23 
punctuation 
character, (See separator) 
in format notation, A-2 
purge file disposition 
relative and indexed files, 9-30 
sequential I/O, 9-29 
PURGE parameter of SEQCHECK compiler 
control option, 17-35 
PURGE phrase . 
in CLOSE statement 
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for multiple-reel tapes, 9-27 
for nonreel files, 9-24 
for relative or indexed I/O, 9-30 
for single-reel files, 9-25 
in MERGE statement, 9-65 
in SORT statement, 9-123 


Q 


qualification, 6-7 
format of, 6-8 
of Kanji data-name, 8-9 
of key names when merging files, 9-66 
rules for, 6-8 
qualifier connectives, 2-5 
queue 
in communication module, 14—2 
of ACCEPT messages, 9-159 
when interrupt not allowed, 9-42 
QUEUE phrase, in communication- 
description (CD) entry, 
14-7 
quotation marks 
as separator, 2-2 
with literals (examples), 2-14 


QUOTE figurative constants, 2-6, (See also 


figurative constants) 
QUOTES figurative constants, 2-6, (See also 
figurative constants) 


R. 


random file access, 3-5, (See also file access) 
in indexed file organization, 5-22 
in relative file organization, 5-19 
in sequential file organization, 5~15 
open modes, 9-79 
RANDOM function in GENERALSUPPORT 
system library, 15-17 
RD, (See report-description (RD) entry, in 
Report Writer) 
READ statement, 3-2 
after START statement, 9-132. 
and deleting records, 9-40 
current-record pointer, 3-6 
effect of seeking, 9-116 
function and syntax, 9-93 . 
in closing sequential files, 9-28 
indexed I/O, 9-98 | 
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open modes, 9-79 
random access for indexed files, 9-96 
reading next record, 9-96 
record size when using RECORD 
~ CONTAINS..DEPENDING ON 
clause, 7-8 
relative I/O, 9-96 
sequential I/O, 9-94 
unsuccessful operation of, 9-96 
using WITH NO WAIT clause with, 5—29 
when status values are updated 
for indexed I/O, 5-31 
for relative I/O, 5-30 
for sequential I/O, 5-27 
when unsuccessful, 9-99 
_ with port files, 3-2 
with sequential access, 9-95 . 
READ-OK phrase, in WAIT statement, 9-158 
read-only storage areas, (See special 
registers) 
reader files, closing, 9-23 
_ reading arecord, (See READ statement) 
REAL phrase 
as indication of internal floating-point 
format, 7-44 
in USAGE clause, 7—42 
RECEIVE MESSAGE phrase, 14-10: 
RECEIVE SEGMENT phrase, 14-10 
RECEIVE statement, in communication 
module, 14—1, 14-22 
RECEIVED BY phrase 
for indexed I/O, 5-21 
for relative I/O, 5-18 
for sequential I/O, 5-14 
in data-description entry, 7-34 
RECEIVED clause, 7-34 
receiving messages, (See message control 
system (MCS)) 
record area, 9-22 
RECORD CONTAINS clause 
errors 
with indexed I/O, 5-32 
with relative I/O, 5-30 
with sequential I/O, 5-29 
for specifying size of data records, 7—7 
in file-description (FD) entry, 7-7 
when deleting records, 9-40 
record description 
contents of, 6-1 
in communication module, 14-13 
RECORD KEY phrase 
in SELECT clause, 5-15 
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indexed I/O, 5-22 
record-name, as user-defined word, 2~14 
records, 6-1, (See also logical records, 
physical records) — . 
concepts, vii 
deleting, 9-40 
description of, 7-17 
determining size of BINARY items, 7-42 
in WORKING-STORAGE SECTION, 7-53 
layout of (example), 6-5 
level-numbers of, 7-19 
linkage in Inter-Program Communication 
(IPC), 13-3 
replacing with REWRITE statement, 
9-108 
using file attributes to account for number 
of, 3-4 
using OF FSET function, 8-12 
01 level-number in, 6-3 
recovery considerations, 9-164 
REDEFINES clause . 
and qualification, 6-8 
syntax, 7-35 
using, 7-35 . 
using VALUE clause with, 7-48 
with CORRESPONDING phrase, 8-26 
REEL phrase 
and reel removal, 9-29 
in CLOSE statement 
for multiple-reel tapes, 9-26 
REF phrase, (See REFERENCE phrase) 
REFERENCE phrase 
in data-description entry, 7-18 
in SELECT clause, 5-13 
in sequential I/O, 5-14 
registers, (See special registers) 
REJECT-OPEN phrase, in RESPOND 
| statement, 9-103 
relation character, reserved word for, 2-10 
relation conditions 
abbreviated combined, 8-23 
definition, 2-12 
of index-names and index data items, 8-17 
of Kanji operands, 8-17 
overview, 8-14 — 
precedence of, 8-24 
using file attributes for, format of, 3-4 
relational operators, 8-15 
relative file organization, 3-5, (See also file 
organization) 
At End condition, reading, 9-95 
declaring, 5-17 
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deleting records, 9—40 

physical record size, 7-7 

random access for, reading, 9-96 

starting sequential access, 9-130 

writing records with, 9-165 
relative I/O, 3-5 

close file actions, 9-30 

current-record pointer, 3-6 

I/O status, 5-30 


of the FILE-CONTROL paragraph, 5-17 


when opening a file, 9~75 
RELATIVE KEY phrase, in SELECT clause, 
5-17 
relative record numbers 
definition, 3-5 
in relative file organization, 5-19 
when writing records, 9-165 
release device disposition, 9-29 
release file disposition 
in sequential I/O, 9-29 
relative and indexed files, 9-30 
RELEASE phrase 
in CLOSE statement, 9-24 
for multiple-reel tapes, 9-27 | 
for relative or indexed I/O, 9-30 
for single-reel files, 9-25 
in MERGE statement, 9-64 
in SORT statement, 9-122 
RELEASE statement, function and syntax 
9-101 
REM function, 8-12 
REMAINDER phrase, in DIVIDE statement, 
9-46 
remainder, obtaining with REM function, 
8-12 | 
remote files, 5-15 
closing, 9-23 
modifying attributes, with CHANGE 
statement, 9-21 
selecting a station, 5-15 
suspending program, 9-158 
with sequential file organization, 5-15 
writing to, 9-163 
REMOVE CRUNCH phrase, in CLOSE 
statement, for nonreel files, 9-24 
REMOVE phrase, in CLOSE statement 
for nonreel files, 9-24 | 
for relative or indexed I/O, 9-30 
remove reel disposition, 9~29 
RENAMES clause 
syntax, 7-50 
with CORRESPONDING phrase, 8-26 
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reopening a file, 9-77 
replacing characters, rules for, 9-55 
REPLACING phrase 
in COPY statement, 9-37, 9-38 
in INSPECT statement, 9-55, 9-59 
REPORT clause, in Report Writer, 12-2 
REPORT FOOTING phrase, in Report 
Writer 
defining, 12-9 
syntax, 12-13, 12-16 
REPORT HEADING phrase, in Report 
Writer 
_ defining, 12-17 
syntax, 12-13, 12-16 
REPORT SECTION 
in Report Writer, 12-2 
overview, 7-1 
rules for using VALUE clause in, 7-49 
Report Writer 
defining value of printable items, 7-46 
detail report-groups, 12-17, 12-19 
ending with TERMINATE statement, 
12-32. 
establishing control breaks with 
CONTROL clause, 12-5 
file description for, 7-3 
FILE SECTION, 12-1 
LINE-COUNTER register, 2-9, 12-30 
linking with GENERATE statement, - 
12-30 
naming reports with REPORT clause of 
FILE SECTION, 12-2 
overview, 12-1 . 
PAGE clause 
defining page length, footing, heading, 
12-7 
regions established (table), 12-10 
PAGE-COUNTER register, 2-10, 12-11, 
12-30 
permissible combinations of RD entries 
(table), 12-27 
printing backup files with PB statement, 
12-5 
producing reports simultaneously with 
CODE clause, 12~3 
program sample, 12~33 
REPORT SECTION, 12-2 
report-group descriptions, 12-12 
COLUMN NUMBER clause, 12-23 .« 
GROUP INDICATE clause, 12-24 
LINE NUMBER clause, 12-14 
NEXT GROUP clause, 12~15 
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SOURCE clause, 12-25 
_ SUM clause, 12—25 
TYPE clause, 12—16 
USAGE clause, 12-18, 12-21, 12-26 
VALUE clause, 12-26 
starting with INITIATE statement, 12-29 
sum counter, 12-27 
titling backup printer file with 
BDREPORT clause, 12-4 
using DECLARATIVES SECTION, 12-33 
report-description (RD) entry, in Report 
Writer, 12-2, 12-12 
report-name, as user-defined word, 2-14 
reports, producing, (See LINAGE clause, 
Report Writer) 
RERUN clause, in I-O-CONTROL paragraph, 
5-25 
rerun points 
establishing, 5-25 
in sequential I/O, 3~5 
RESERVE clause 
in SELECT clause, 5-13 . 
in SPECIAL-NAMES paragraph, 5-10 
indexed I/O, 5-22 — 
relative I/O, 5-18 
sequential I/O, 5-15 
RESERVE phrase, 5-10 
reserved words 
application-specific, B-6 
context-sensitive, B—6 
definition, 24 
for arithmetic operators, 2-10 
in format notation, A-2 
lists of, B-1 
RESET ON phrase, in SUM clause, 12-25 
RESET option action indicator, 17-11 
RESET phrase | 
in CAUSE statement, 9-19 
in Report Writer, 12~22 
in WAIT statement, 9-158 
RESET statement, function and syntax, 
9-102 
RESPOND statement 
examples, 9-105 
_ » function and syntax, 9-102 
RESPONSE-TYPE phrase, in RESPOND 
statement, 9-103 
resultant identifiers, 8—25 
retain file disposition for sequential I/O, 9-29 
RETURN statement 
function and syntax, 9-106 
when merging files, 9~67 
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REVERSED phrase, in OPEN statement, 
9-75, 9-76, 9-77 
rewind reel disposition, 9-29 
REWRITE statement 
function and syntax, 9-108 
open modes, 9-79 
when status values are updated 
for indexed I/O, 5-31 
for relative I/O, 5-30 
for sequential I/O, 5-27 
RF phrase, (See REPORT FOOTING 
phrase, in Report Writer) 
RH phrase, (See REPORT HEADING 
phrase, in Report Writer) 
ROUNDED phrase 
in ADD statement, 9-3 
in COMPUTE statement, 9-34 
in DIVIDE statement, 9-45 
in MULTIPLY statement, 9-74 
in SUBTRACT statement, 9-136 
overview, 8-25 
routine-name, as user-defined word, 2-14 
routing messages, (See message control 
system (MCS)) 
rules 
for arithmetic expressions, 8-7 
_ for condition evaluation, 8-24. 
for statement formats, 8-26 
RUN statement, 8-1 
function and syntax, 9-110 
relationship to PROCEDURE DIVISION 
parameters, 8-1 
with DETACH statement, 941 
run time 
naming called program, 9-13 
specifying logical-record length, 7-8 
run unit 
definition, 17-38 
ending, 13—7 


S 


S, edit character in PICTURE clause, 6-17 
using SIGN clause with, 7-37 
SAME clause, 5-26 
SAME RECORD AREA clause, in 
I-O-CONTROL paragraph, 5-25 
sample program, (See example program for) 
save file disposition 
relative and indexed I/O, 9-30 
sequential I/O, 9-29 
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save file with remove disposition 
relative and indexed files, 9-31 
sequential I/O, 9-29 
SAVE FOR REMOVAL phrase, in CLOSE 
statement 
for multiple-reel tapes, 9-27 
for single-reel files, 9-25 
SAVE phrase | 
in CLOSE statement 
for nonreel files, 9-24 
for relative or indexed I/O, 9~30 .- 
in MERGE statement, 9-66, 9-68 
in SORT statement, 9-126, 9-127 
save unit disposition, with CLOSE statement, 
9-29 
scaling position character, when editing, 6-16 
Screen Design Facility (SDF), vi 
Screen Design Facility Plus (SDF Plus), vi 
SD, (See sort merge description (SD) entry) 
SDF (Screen Design Facility (SDF)), vi 
SDF Plus (Screen Design Facility Plus), vi 
SEARCH ALL statement, 9-115 
SEARCH statement 
as conditional expression, 8-13 
nonserial search operation, 9-115 
SEARCH ALL statement (binary search), 
9-115 
serial search operation, with two WHEN 
phrases, 9-113 
syntax, 9~111 
with undigit literals, 2-17 
with USAGE clause, 7-45 
section headers, location in source program, 
1-6 
section-name 
as user-defined word, 2-14 
in qualification, 6-9 
sections, 8-2 
overview, 1-2 . 
SECURITY paragraph, 4-1 
SEEK statement 
current-record pointer, 3-6 
syntax, 9-116 
when status values are updated 
for sequential I/O, 5-27 
SEGMENT phrase, in RECEIVE statement, 
14-23, 14-24 
segment size, changing with CODE 
SEGMENT-LIMIT clause, 5-4 
SEGMENT-LIMIT clause 
in OBJECT-COMPUTER paragraph, 5-3 
reasons for ignoring, 10-2 
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segment-number 
as user-defined word, 2—14 
uniqueness of, 2-12 
segmentation module, 10-1 
CALL statement with, 13-5 
SELECT clause, 5-13 
for indexed I/O, 5-21 
for relative I/O, 5-17 
for sequential I/O, 5-14, 5-17, 5-21 
Semantic Information Manager (SIM), vi 
semicolon 
as separator, 2-2 
in COPY statement, 9-39 
in format notation, A-2 
SEND statement 
and SPECIAL-NAMES paragraph, 5-7 
in communication module, 14~1, 14-25 
with integer value, 14-3 
sending messages, (See message control 
system (MCS)) | 
sentences 
definition, 1-4, 8-3 
types of ; 
compiler-directing, 8-5 
conditional, 8-4 
imperative, 8-5 


_ SEPARATE CHARACTER clause 


in data-description entry, 7-18 
in SPECIAL-NAMES paragraph, 5-7 
separate compilation 
changed records, 17-6 
host file creation, 17-5 
restrictions, 17-6 
separator 
definition, 2-2 
in COPY statement, 9-37 
-in PICTURE character string, 2~3 
SEPCOMP compiler control option, 17-35 
SEQ or SEQUENCE compiler control option, 
17-36 
SEQCHECK compiler control option, 17-35 
sequence area, in source program, 1-6 
Sequence Base compiler control option, 17-37 
SEQUENCE clause, in OBJECT- 
COMPUTER paragraph, 
5-3 


. Sequence Error condition, 5-32 


Sequence Increment compiler control option, 
17-37 
sequence number 
checking of 
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with SEQCHECK compiler control 
option, 17-35 — 
with TADS, 17-41 
in source program, 1-6 
sequential file access, open modes, 9-79 
sequential file organization 
At End condition, reading, 9-94 
concepts, 3-5 
declaring, 5-13 
file access with ACCESS MODE clause, 
5-15 
formats for writing records, 9~161 
writing records with, 9-165 
sequential I/O, 3-5 
close-file actions, 9-28 
current-record pointer, 3-6 
1/O status, 5-27 
of the FILE-CONTROL paragraph, 5-13 
open modes, 9-79 
when opening a file, 9-75 
with CLOSE statement, 9-23 
serial search operation, with SEARCH 
statement, 9-112 
SET option action indicator, 17-11 
SET statement, 9-116 
validity of operands (table), 9-118 
with PERFORM statement, 9-89 
with SEARCH statement, 9-116 
with USAGE clause, 7-45 
sets of elementary items, 6-2 . 
SHARING compiler control option, 17-38 — 
effect on library availability, 15-14 
effect on library state, 15-9 
in libraries, 15-5 
sharing memory areas, in sequential I/O, 3-5 
Short Block condition © 
for indexed I/O, 5-32 
for relative I/O, 5-30 
for sequential I/O, 5-29 
SHORT-DATE type, 16-16 
sign, 7-37 
and PICTURE clause, 7-30 
changing, in arithmetic expressions, 8-6 
conditional expression, 8-19 
control symbols for editing, 6-18 
defining position of, 5-10 
editing symbol, 6-17 
precedence of in conditions, 8-24 
when moving data, 9-70 
with fixed insertion editing, 6-20 
with floating insertion editing, 6-21 
with SYNCHRONIZED clause, 7-39 
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with USAGE IS INDEX clause, 7-45 
SIGN clause, 7-87, (See also sign) 
SIM (Semantic Information Manager), vi 
simple conditions, 8-14 
class, 8-18 
combining, 8-20 
comparing numeric operands, 8-17 
condition-name, 8-19 
event-identifier, 8-20 
negated, 8-21 
relation, 8—14 
sign, 8-19 
simple insertion editing, (See editing) 
single-precision numeric format 
CALL statement parameters, 9-15 
floating-point literals, 2-16 . 
of REAL data item, 7-44 
partial words, 9-72, 9-111 
with USAGE IS REAL clause, 7-44 
single-reel tape file, 9-24 
size considerations 
in comparing relation conditions, 8-17 
of elementary items, 7-31 
SIZE ERROR phrase 
in SUBTRACT statement, 9-136 
overview, 8-25 
size-error determination 
overview, 8-25 
with USAGE IS BINARY TRUNCATED 
clause, 7-43 
SL (Support Library) command role in 
linking libraries, 15-17 


slash (/) character 


for editing in PICTURE clause, 6-18 
for page ejection, 1-10 
sort merge description (SD) entry 
location in source program, 1-6 
records in, 7-6 
syntax, 7-5 
SORT phrase, in SELECT clause, 5-24 
SORT statement, 5-7, (See also sorting 
files) 
automatically moving records to first file, 
9-126 
automatically writing records to new file, 
9-127 
closing, 9-27 
in localized application, 16-17 
input procedures, 9-125 
output procedures, 9-126 
placement in program, 9-122 
rules for keys, 9-124 
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sorting on keys, 9-123 

syntax, 9-121 

when equating file attributes, 7-11 

with RELEASE statement, 9-101 
sorting files, 5-3, (See also SORT 

statement) 

assigning collating sequence, 5-4 

defining collating sequence, 5-7 

effect of coded character set, 16-9 


identifying in FILE-CONTROL paragraph, 


5-24 
RELEASE and RETURN statement 
restrictions, 9-85 
specifying memory size or disk size, 5-3 
using RETURN statement to obtain 
records, 9-106 
work areas for, 9-123 
SOURCE clause 
in communication-description (CD) entry, 
14-7 
in Report Writer, 12-22, 12-25 
SOURCE file, used by compiler, 17-14 


' source files, 17-12 


source listing, page ejection of, 1-10 
source program 
area A of, 1-6 
area B of, 1-6 
format of, 1-5 
overview, 1-1 
producing a listing, 17-27 
sequence number area of, 1-6 
source record, 9-168 : 
SOURCE-COMPUTER paragraph, 5-2 
using WITH DEBUGGING MODE clause 
with, 11-2 
space 
as separator, 2—2 
in coding, 2-2 
in format notation, A—2 
SPACE figurative constants, 2-6, (See also 
figurative constants) 
space-fill 
editing symbol for, 6-18 
in JUSTIFIED clause, 7-22 
_ when aligning data, 6-10 
when moving data, 9-70 
SPACES figurative constants, 2-6, (See also 
figurative constants) 
spacing — | 
editing symbol for, 6-16 
of logical pages, during printing, 7-14 
SPEC compiler control option, 17-39 
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special characters, in format notation, A-2 
special insertion editing, (See editing) 
special registers 
in ACCEPT statement, 9-2 
overview, 2~8 
used by Report Writer, 12-11, 12-30 
special-character words 
definition, 2-10 
overview, 2—10 
SPECIAL-NAMES paragraph 
for naming called program, 9-18 
overview, 5-5 
_ with ACCEPT statement, 9-1 
with DISPLAY statement, 9-44 
spooling, (See backup files) 
stack 
for dependent processes, 9-92 
OWN variables on, 7-28 
using RECEIVED clause with, 7-34 
STACK OVERFLOW fault, 9-85 
STACK SIZE clause, in OBJECT- 
COMPUTER paragraph, 
5-3 
STACK SIZE option, 5-4 
standard alignment rules, 6-9 
standard data format 
editing considerations, 7-30 
for alphabetic data items, 7-30 
for alphanumeric data items, 7-30 
size considerations, 7-31 
USAGE IS DISPLAY phrase with, 7-44 
STANDARD-1 clause, in SPECIAL-NAMES 
paragraph, 5-7 
START statement, 9-130 
current-record pointer, 3-6 
open modes, 9-79 . 
when status values are updated 
for indexed I/O, 5-31 
for relative I/O, 5-30 
statements 
definition, 1-5, 8-3 
- formats of, 8-26 
status of execution 
for indexed files, 5-24 
for relative files, 5-19 
for sequential files, 5-16 
types of 
compiler-directing, 8-5 
conditional, 8-4 
imperative, 8-5 
station device, 5-15, (See also remote files) 
accessing as REMOTE file, 3-2 
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STATIONLIST file or task attribute, 9-21 
STATISTICS compiler control option, 17-39 
STATUS clause, (See FILE STATUS 
. clause) 
status condition, in communication module, 
14-11 
STATUS KEY clause 
in communication-description (CD) entry, 
14-13 
STATUS KEY clause, in communication- 
description (CD) entry, 
14-7 
status key 1 
for indexed I/O, 5-31 
for relative I/O, 5-30 
for sequential I/O, 5-27 
status key 2 
for indexed I/O, 5-32 
for relative I/O, 5-30 
for sequential I/O, 5-27 
STATUS phrase, in SELECT clause, 5-13 
status reporting,5-16 
exception handling with USE statement, 
9-152 
for AWAIT-OPEN statement, 9-10 
for indexed I/O 
role of operating system in, 5-24 
status key values, 5-31, 5-32 
‘for OPEN statement, 9-83 
for relative I/O 
role of operating system in, 5-19 
status key values, 5-30 
for RESPOND statement, 9~105 
for sequential I/O, 5-27 
role of operating system in, 5-16 
status key values, 5-27 
when closing a file, 9-33, 9-105 
when closing a file, 9-34 
when deleting a record, 9-41 
when writing to a file, 9-160 
with START statement, 9-130, 9-131 
STATUS task attribute, 9-41 
STOP literal statement 
as part of IPC run-unit, 9-132 
syntax, 9-132 
STOP RUN statement 
actions taken by, 9~132 
execution of 
in called program, 9-13 
in library program, 15-4 
STOP statement 
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in Inter-Program Communication (IPC), 
13-7 
syntax, 9-132 — 
with undigit literals, 2-18 
STRING phrase, for calling libraries, 15-6 
STRING statement 
syntax, 9-133 
with undigit literals, 2-18 
SUB-QUEUE-1 phrase, in communication- 
description (CD) entry, 
14-7 
SUB-QUEUE-2 phrase, in communication- 
description (CD) entry, 
14-7 
SUB-QUEUE-S phrase, in communication- 
description (CD) entry, 
14-7 
subfiles 
definition, 3-2 
index, 3-3 
subject of condition, 8-15 
subscripts, 6-12 
in conditional expressions, 8-14 
SUBTRACT statement, 9-136, (See also 
subtraction) 
SIZE ERROR and CORRESPONDING 
phrases, 8-26 
storing results in multiple fields, 8-27 
subtraction, 2-10 
arithmetic symbol for, 8-6 
reserved word for, 2-10 
Successful Completion condition, 5-27 
for indexed I/O, 5-32 
for relative I/O, 5-30 
for sequential I/O, 5-27 ) 
SUM clause, in Report Writer, 12-22, 12-25 
sum counter, 12-27 
SUMMARY compiler control option, 17-40 
suspending a program 
with STOP statement, 9-132 
with WAIT statement, 9-158 
SW1 through SW8 external switches, 5-7 
SYMBOLIC clause, in communication- 
description (CD) entry, 
14-7 | 
SYMBOLIC DESTINATION clause, 14-12, 
14-13 
Symbolic ID compiler control option, 17-40 
SYNC clause, (See SYNCHRONIZED 
clause) 
SYNCHRONIZED clause 
data-description entry, 7-18 
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definition, 7-38 
synchronized output 
in REWRITE statement, 9-108 
in WRITE statement, 9-163 
WRITE statement, 9-164 
synchronous processes 
task-attribute identifiers in, 3-6 
with CONTINUE statement, 9-35 
syntax diagrams, (See format notation) 
system calls, 9-18 
system collating sequence, designating, 16—16 
system commands 
AX (accept), 9-159 
OF (optional file), 9-30 
RM (remove), 9-30 
SL (support library), 15-17 
system date 
formatting by convention, 16-78 
formatting by template and language, 
16-75 
moving to data item, 16-17 
system default ccsversion, 16-5 
system options, AUTORM (autoremove), 
9-29 
system time 
formatting by convention, 16-78 
formatting by template and language, 
16-75 
moving to data item, 16-17 
system-name, as user-defined word, 2-12 
SYSTEM/CCSFILE, 16-4 
SYSTEM/INTERACTIVEXREF utility, 17-3 
SYSTEM/XREFANALYZER utility 
failure of, 17-4 
role of, 17-3 | 
starting, 17-31 


T 


tables, vii, 6-10, (See also OCCURS clause) 
- abnormal termination, 7-27 
accessing, 6-12 
concepts, vii 
defining size of, 7-25 
defining with OCCURS clause, 7-24 
errors, 6-13 
establishing index points for table 
handling, 9-116 
' global arrays, 7-21 
in ascending key order, 7-26, 7-27 
in descending key order, 7-26, 7-27 
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indexing 
by name, 6-14 
by relative number, 6-14 
by subscript, 6-14 
one-dimensional (example), 6-11 
rules for using VALUE clause in, 7-48 
searching with SEARCH statement, 9-111 
subscripting, 6-12 
three-dimensional (example), 6-12 
using RECEIVED clause with, 7-34 
using REDEFINES clause with, 7-35 
using task attributes with, 3-7 
with RENAMES clause, 7-50 
with SYNCHRONIZED clause, 7-39 
with USAGE IS EVENT clause, 7-41 
TADS (Test and Debug System), 17-40 
TADS compiler control option, 17-40 
TAG-KREY phrase, in SORT statement, 9-122 
TAG-SEARCH phrase, in SORT statement, 
9-122 
TALLYING phrase 
in INSPECT statement, 9-53 
in UNSTRING statement 
execution of, 9-142, 9-145 
function of, 9-148 
Syntax, 9-140 . 
tallying, rules for, 9-54 
tape devices, in closing sequential files, 9-28, 
9-29 
tape files 
closing 
multiple reels, 9-26 
single reel, 9-24 
for sorting or merging, 5-24 
with a single reel, 9-24 
with more than one file on a reel, 5-26 
with sequential file organization, 5-13 
_ with variable-length records, 7-8 
TARGET compiler control option, 17—42 
target record, 9-168 
task attributes 
as event-identifiers for CAUSE statement, 
9-19 
identifiers, 3-6 
interrogating, 3-8 
mnemonic, 3-8 
modifying 
with CHANGE statement, 9-20 
with SET statement, 9-116 
name of | 
EVENT, 3-8 
OPTION, 3-9, 11-1 
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POINTER, 3-8. 
STATIONLIST, 9-21 
STATUS, 9-41 
TASK, 3-8 
setting switches SW1 through SW8, 5-7 
testing, 8-20 
TASK data item, referring to, 7-43 
task item, dissociating a procedure from, 9-41 
TASK phrase 
in data-description entry, 7-18 
in USAGE clause, 7-42 
TASK task attribute, 3-8 
task-attribute identifiers, 3-6 
MYSELF and MYJOB, 3-7 
tasking 
calls 
for parameter mapping, 9-14 
with EXIT PROGRAM statement, 9-50 
concepts, 3-1 
naming identifiers received as parameters 
in, 8-1 
tasks 
asynchronous, starting independently, 
9-110 
CALL statement, for transferring control 
to, 9-12 
critical block exit, 9-92 
dependent, passing control to, 9-49 
DETACH statement, for ending of, 9-41 
identifying a program to be used as, 9-152 
parameter passing in, 7-23 
starting, 9-92 
USAGE clause with, 7-43 
TCP/IP (Transmission Control 
lease ad Protocol), B-106 
template 
date, 16-50 
for creating convention, 16-11 
for formatting time . 
creating, 16-56 
format 
obtaining from convention, 16-81 


TEMPORARY compiler control option, 17-43 


temporary libraries, 15-15 

- temporary libraries, initial state of, 15-9 

terminal device, accessing as REMOTE file, 

3-2 

TERMINATE statement, in Report Writer, 
12-32 

termination, normal, 9-132 

Test and Debug System (TADS), generating 
code for, 17-40 
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text 
comparing in localized applications, 16-98 
comparison of, 16-7 
- modifying with mapping table, 16-113 
rearranging by ccsversion escapement 
rules, 16-102 
searching for characters specified by 
truthset, 16-109 
TEXT LENGTH clause, in communication- 
description (CD) entry, 14-7, 
14-13 
text-name 
as user-defined word, 2—14 
in COPY statement, 9-37 
qualification of, 6-7 
THEN phrase, with IF statement, 9-52 
THROUGH phrase 
in alphabet-name clause, 5-9 
in VALUE clause, 7-52 
time 
formatting by convention and language, 
16-58 
formatting by template, 16-56 
international formatting, 16-12 
numeric, display model, 16-47 
system-provided 
formatting by convention, 16-78 
formatting by template and language, 
16-75 
TIME special register, 2-10 
in ACCEPT FROM statement, 9-2 
timeout condition 
for indexed I/O, 5-32 
Timeout condition 
for relative I/O, 5-31 
for sequential I/O, 5-29 
TIMER special register, 2~10 
in ACCEPT FROM statement, 9-2 
TODAYS-DATE special register, 2-10 
in ACCEPT FROM statement, 9-2 
TODAYS-NAME special register, 2-10 
in ACCEPT FROM statement, 9-2 
TOP margin 
in file-description (FD) entry, 7~14 
in LINAGE clause, 7-14 
TPS (Transaction Processing System), vi 
transaction functions in DCILIBRARY, 14-1 
Transaction Processing System (TPS), vi 
translating data from one coded character set 
to another, 16~31 
translation tables, 5-8 
transliteration table, 16-6 
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Transmission Control Protocol/Internet 
Protocol (TCP/IP), 9-164 
transmission errors for sequential I/O, 5-27 
transmission indicator schedule, 14-28 
TRUNCATED phrase 
in data-description entry, 7-18 
in USAGE clause, 7-42 
truncation 
in arithmetic statements, 8-26 
in division, 9-47 
in JUSTIFIED clause, 7-22 
in ROUNDED phrase, 8-25 
in START statement, 9-131 
in SYNCHRONIZED clause, 7-39 
in USAGE IS BINARY TRUNCATED 
clause, 7-43 
of parameters passed 1 in RUN statement, 
9-111 
rules with VALUE clause, 7-47 
when aligning data, 6-9 
when moving data, 9-69 
with exponentiation, 8-7 
with floating insertion editing, 6-22 
truth test, 8-19 
truthset, 16-6 
alphabetic, 16-17 
use in text searches, 16-109 
TYPE clause, 7~39 
in Report Writer, 12-13, 12-16 
type values for CENTRALSUPPORT library 
parameters, 16-28 


U 


undigit literals, (See literals) 
unexpected J/O error 
for sequential I/O, 5~29 
Unexpected I/O error 
for indexed I/O, 5-32 
for relative I/O, 5-31 
UNIT phrase, in CLOSE statement, 9-96 
UNLOCK statement, 9-139 
UNSTRING statement, 9-139 
before and after (examples), 9-146 
causes of overflow condition, 9-143, 9-146 
coding of (example), 9-149 
transferring data with, 9-143, 9-145 
with undigit literals, 2~18 
UP BY phrase 
in CHANGE statement, 9-21 
in SET statement, 9-118, 9-119 
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‘UPON phrase 


in DISPLAY statement, 9-43 
in SUM clause, 12-25 
URGENT phrase, in WRITE statement, 
9-163 
USAGE clause 
formatting of data item with, 7-41 
in relation conditions, 8-14 
in Report Writer, 12-18, 12-21, 12-26 
with CORRESPONDING phrase, 8-26 
with variable-length records, 7-8 
USAGE EVENT event-identifier, 3-8 
USAGE IS DISPLAY phrase 
character code set for, 5-8 
for standard data format, 7-44 
in Report Writer, 12-13 
searching and replacing group items, 9-54, 
9-55, 9-57 
using extended functions with, 8-9 
using 5 edit character with, 6-17 
using SIGN clause with, 7-37 
using UNSTRING statement with, 9-141, 
9-144 
using with STRING statement, 9-134 
with CODE-SET clause, 7-16 
USE AS INTERRUPT PROCEDURE 
statement, 9-157 
USE BEFORE REPORTING statement, 
12-33 
USE EXTERNAL statement 
for calling program at run time, 9-13 
USE FOR DEBUGGING statement 
in debug module, 11-2 
with OPTIMIZE compiler coe option, 
17-33 - 
USE statement 
as compiler-directing verb, 8-5 
syntax, 9-152 
using ATTACH statement with, 9-7 
using DETACH statement with, 9-41 
_using in Report Writer, 12-32 | 
with AFTER phrase, 9-152 
USER clause, 7-17 
USER compiler control option, 17-44 
user program in libraries, 15-1 
user-defined words, 2-12 
alphabet-name, 2-12 
CD-name, 2-12 
condition-name, 2—12 
data-name, 2-12 
family-name, 2-12 
file-name, 2-12 
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index-name, 2—12 
level-number, 2-12 
library-name, 2-12 
mnemonic-name, 2—12, 2-13 
paragraph-name, 2-13, 2-14 
program-name, 2-14 
qualification of, 6—7 
record-name, 2~14 
report-name, 2-14 
routine-name, 2-14 
section-name, 2-14 
segment-name, 2—14 
system-names, 2-12 
text-name, 2-14 

USING phrase 
in CALL statement, 9-14 

with task identifier, 9-13 

in libraries, 15-1 
in SORT statement, 9-126 


V 


V, edit character in PICTURE clause, 6-17 
VA clause, (See VALUE clause) 
VALIDATE NAME RETURN NUM 
_ procedure, 16-93 
VALIDATE_NUM_RETURN NAME 
procedure, 16-95 
VALUE clause, 7-46 
in CHANGE statement, 9-21, 9-22 
in data-description entry, 7-18 
in file-description (FD) entry, 7-4 
in Report Writer, 12~22, 12-26 
in SET statement, 9-120 
rules with condition-name, 7-52 
with undigit literals, 2-17 
value compiler control options, 17-8 
VALUE OF clause 
coding of (example), 7-12 
in file description (FD) entry, 7-10 
in sort merge description (SD) entry, 7~10 
variable-length records 
errors 
with indexed I/O, 5-32 
with relative I/O, 5-30 
with sequential I/O, 5-29 
grouped into one physical record, 7-6 
rules for, 7-8 
variables 
- allocation by compiler, method of 
investigation, 17-29 
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declared as type OWN, 7-28 
global, 7-21 
in arithmetic expressions, 8-8 
local, 7-23 
VARYING phrase 
in PERFORM statement 
with one condition, 9-88 
with two conditions, 9-84 
with UNTIL phrase, 9-87 
in SEARCH statement, 9-111 
vectors, (See tables) 
verbs 
as keywords, 2-8 
compiler-directing, 8-5 
imperative, 8-5 
VERSION clause, 7-17 
VOID compiler control option, 17-44 
volume-id, 5-26 
VSNCOMPARE TEXT procedure, 16-98 
VSNESCAPEMENT procedure, 16-102 
VSNGETORDERINGFOR ONE TEXT 
procedure, 16-105 
VSNINSPECT_TEXT procedure, 16-7, 
16-109 . 
VSNTRANS TEXT procedure, 16-6, 16-113 


W 


WAIT phrase 

in AWAIT-OPEN statement, 9-9 

in CLOSE statement, 9~31 

in OPEN statement, 9-81 
WAIT statement 

syntax, 9-157 

_with CAUSE statement, 9-19 

WARNFATAL compiler control option, 17-45 
warning messages 

in libraries, 15-11 

suppressing printing of, 17-39, 17-45 

treating like syntax errors, 17-45 
WARNSUPR compiler control option, 17-45 
WFL, (See Work Flow Language (WFL)) 
WHEN phrase, in SEARCH statement, 9-111 
WITH DEBUGGING MODE phrase 

as compile-time switch in debug module, 

11-1 

in SOURCE-COMPUTER paragraph, 5-2 

WITH FOOTING phrase, in file-description 
(FD) entry, 7-14 


_ WITH NO WAIT phrase 


- in OPEN statement, 9-9, 9-76, 9-77 
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in READ statement, 9-94 
in WRITE statement, 9-163 
WITH POINTER phrase 
in STRING statement, 9-133 
in UNSTRING statement, 9-140 
WITH URGENT phrase, in WRITE 
statement, 9-163 
word boundaries 
for real and double data items, 7-44 
with binary data items, 7-42 
with SYNCHRONIZED clause, 7-39 
words 
allowed use in program, 2-4 
in character string, 2-3 
lowercase, A-2 
maximum length of, 2-4 
optional, A-2 
required, A-2 
reserved, 2-4, B-1 
underlined, A-2 
uppercase, A-2 
user-defined, 2-12 
work areas, for sorting, 9-123 
Work Flow Language (WFL) 
calling program from, 7-35 
family assignment effect on library linking, 
15-17 | 
parameters (table), 9-16 
printing backup disk files with, 12-4 
setting external switches with, 5-7 
_ Starting compilation from, 17-14 
with CALL SYSTEM statement, 9-18 
working-storage 
data, 7-1 
"defining initial values, 7-46 
noncontiguous, 7-53 
rules for using VALUE clause in, 7-49 
WORKING-STORAGE SECTION 
coding of (example), 7-54 
description of data in, 7-58 ? 
overview, 7-1 
WRITE DELIMITED statement, 9-167 
WRITE FORM statement, 9-160 
WRITE statement 
and SPECIAL-NAMES paragraph, 5-7 
Broadcast Write error, 5—29 
defining logical page size of, 7-14 
effect of seeking, 9-116 
in closing sequential files, 9-28 
open modes, 9-79 
syntax, 9-160 
when status values are updated 
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for indexed I/O, 5-31 
for relative I/O, 5-30 
for sequential I/O, 5-27 
with indexed I/O, 9-166 
with port files, 3-2 
with relative I/O, 9-165 
with sequential file access, 3-5 
with sequential I/O, 9-165 
writing a file, 7-14 
writing a record, 5-27 
writing a file, (See WRITE statement) 
writing a record, (See WRITE statement) 
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X, edit character in PICTURE clause, 6-17 
XDECS compiler control option, 17-45 
XREF compiler control option, 17-46 
XREFFILE file, used by compiler, 17-16 __ 
XREFFILES compiler control option, 17-46 
XREFS compiler control option, 17-47 


Z 


Z, edit character in PICTURE clause, 6-18 
zero (0), edit character in PICTURE clause, 
6-18 
ZERO figurative constants, 2-6, (See also 
figurative constants) 
ZERO keyword, 8-20 
zero value 
division by, 8-25 ~ 
in comparing numeric operands, 8-16 
returned by functions, 8-11 
truth test for, 8-20 
zero-fill 2 
when aligning data, 6-9 
when moving data, 9-70 
zero-suppression 
editing, (See editing) 
symbol (*) with BLANK WHEN ZERO 
clause, 7-29 
ZEROES figurative constants, 2-6, (See also 
figurative constants) 
ZEROS figurative constants, 2-6, (See also 
figurative constants) | 
zone 
editing considerations for, 6-17 
maintaining sign in, 6-17, 7-38 
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masking of with OPTIMIZE option, 17-33 


. (period), 6-18 
* (asterisk), edit character in PICTURE 
clause, 6-18 
— (minus sign), 6-18 
/ (slash) character 
for editing in PICTURE clause, 6-18 
for page ejection, 1-10 
, (comma), 6-18 
$ (dollar currency symbol) 
edit character in PICTURE clause, 6-19 


0, edit character in PICTURE clause, 6-18 
01-level-numbers, 6-4, (See also 
level-number) 
for records, 6-3 _ 
for redefining memory areas, 7-19 
66 level-numbers, 6—4, (See also 
level-number) 
record layout, 6-3 
redefining records with RENAMES clause, 
7-50 
syntax, 7-50 
77 level-numbers, 6-4, (See also 
level-number) 
record layout, 6-3 
stack operand, 7-21 
syritax, 7-53 
88 level-numbers, 6-4, (See also 
level-number) 
format of condition-name, 7-51 
record layout, 6-3 
9, edit character in PICTURE clause, 6-18 
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